China Stocks

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

The description adds significant behavioral context beyond annotations, such as default free model, BYO key requirement for Anthropic, and return format details (score, confidence, signals, raw_response). 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 sentences with front-loaded core action and output. No unnecessary words, every sentence adds value.

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

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

Despite no output schema, the description fully covers purpose, usage, behavioral traits, parameter semantics, and return format. It is complete for a tool of this complexity.

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

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

Schema description coverage is 100% with parameter descriptions. The description adds extra context like default model, free usage, and BYO key, enhancing understanding beyond schema alone.

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

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

The description clearly specifies the verb 'probe', the resource 'one or more LLMs', and the output 'score visibility (0-100) per model'. It distinguishes from siblings by detailing default model and optional Anthropic probing.

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

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

The description explicitly mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not contrast with alternatives like scan_competitor_ai_presence, but provides clear context for when to use.

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

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

Annotations already provide safety traits (readOnlyHint, idempotentHint, etc.). Description adds valuable context: source (Eastmoney datacenter) and keyless access, no contradictions. Fulfills behavioral disclosure 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 with front-loaded key information (what it does, metrics, and example query). No redundant or unnecessary text.

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

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

Despite no output schema, description lists all returned fields (consensus EPS, P/E, net profit, total revenue). Combined with annotations (readOnlyHint, etc.), it provides a complete picture for a simple data retrieval tool.

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

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

Only one parameter 'symbol' with 100% schema coverage. Description reinforces that it's a Chinese A-share code and gives example in query form, but does not add significant new meaning beyond schema description.

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

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

Description clearly states it provides analyst consensus estimates for Chinese A-share stocks, listing specific metrics (EPS, P/E, net profit, revenue) per forecast year. It distinguishes from siblings like 'ashares_earnings_forecast' by focusing on consensus estimates from Eastmoney datacenter.

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 a typical query example ('analyst estimates / 盈利预测 / forecast EPS for a China A-share like 000988'), indicating when to use. Does not explicitly exclude alternatives or mention when not to use, but context is clear enough for an AI 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: 'Most recent reports first' explains ordering, and 'Source: Eastmoney datacenter (keyless)' clarifies data provenance and access requirements. 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 moderately concise at a few sentences, front-loading the main purpose and key details. It includes example queries and source information without being verbose. Could be slightly tighter, but still effective.

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

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

Given there is no output schema, the description comprehensively explains what the tool returns (profit range, YoY change, forecast type, reason) and includes ordering and data source. It also provides example symbol queries. For a simple 2-parameter tool, this is complete and sufficient for an agent.

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

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

Schema coverage is 100% and both parameters have descriptions. The description does not add further parameter semantics beyond the schema, but it does explain the return value structure (e.g., profit range, YoY change), which indirectly helps parameter understanding. Thus, baseline 3 is appropriate.

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

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

The description clearly states the tool provides company-issued earnings guidance for Chinese A-share stocks, specifying the data points (profit range, YoY change, forecast type, reason). It distinguishes from sibling tools like ashares_analyst_consensus by emphasizing 'company's own forecast announcements' and includes example query terms, making the purpose unambiguous.

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

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

The description does not explicitly say 'use this tool when you need X, not Y', but it provides clear context: it answers queries about '业绩预告' and 'earnings forecast/guidance for a China A-share company'. The mention of source and default ordering implies appropriate use cases, but lacks explicit alternatives or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context: the data source (Eastmoney, keyless access) and the exact fields returned. It also clarifies the price limit rules. No contradictions with annotations. This exceeds the baseline for annotation-covered tools.

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

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

The description is a single well-organized paragraph that front-loads the main function, then elaborates on fields and source. It avoids fluff and each sentence contributes useful information. Slightly dense due to the field list, but efficient and readable.

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

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

With no output schema, the description thoroughly explains what the tool returns, listing all stock attributes. It also explains the limit percentage rules and source. The parameters and defaults are well-covered by the schema, so the description complements the structured data 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?

The input schema provides 100% coverage for both parameters (date and limit), including defaults and ranges. The description adds no additional parameter semantics beyond what the schema already documents, such as the total count always being returned. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: to provide the A-share limit-up board for a trading day, including the count and ranked list of stocks. It specifies the scope (+10%/+20% limits) and distincts from sibling A-share tools (e.g., quotes, consensus) by focusing on limit-up events. The verb 'answers' and example queries make the purpose concrete.

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

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

The description provides clear context for use, such as answering specific questions like 'how many A-shares hit limit up today' and 'top limit-up stocks'. It implies when to use this tool over alternatives (e.g., when limit-up data is needed), but does not explicitly exclude alternatives or mention when not to use it. This aligns with 'clear context, no 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, openWorldHint, idempotentHint, and destructiveHint, so the description carries a lower burden. It adds value by disclosing the data sources (Sina + Eastmoney, keyless) and the sentiment gauge (limit-up count). 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 a single, well-structured sentence beginning with the core purpose, followed by details and example queries. No wasted words; every sentence adds value.

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

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

Given no output schema and no parameters, the description covers the key output fields (index levels, change %, range, turnover, limit-up count). It could specify the exact structure or field names, but overall it's sufficiently complete for a simple snapshot 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?

No parameters exist (schema coverage 100%). With zero parameters, the baseline is 4. The description explains what the output contains, compensating for the lack of explicit parameter docs.

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

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

The description uses a specific verb ('snapshot') and clearly states it provides headline index levels, change %, day range, turnover, and limit-up count. It distinguishes from siblings like ashares_quote (individual quotes) and ashares_limit_up (details on limit-up) by being a broad market overview.

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 includes example queries ('how is the China A-share market doing', 'Shanghai Composite today'), making it clear when to use. It does not explicitly mention when not to use or name alternatives, but the sibling context implies this is for aggregate snapshots. Slight room for improvement.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable context: it specifies 'real-time', lists all returned fields (name, price, change, etc.), mentions the source (Sina, keyless), and clarifies that multiple codes can be queried at once. 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 compact (4 sentences) and front-loaded. The first sentence states the core purpose, followed by return fields, usage syntax, an example, and the source. Every sentence adds value 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?

Despite lack of output schema, the description explicitly lists all return fields (name, current price, change%, etc.). Combined with the clear parameter usage and source info, this is a complete description for a simple read-only tool.

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

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

The input schema already describes the 'symbols' parameter. The description enriches it by explaining the code format (6-digit, prefixes optional), providing an example, and noting that lists are comma-separated. This goes beyond the schema's description.

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

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

The description clearly states 'Real-time quote(s) for Chinese A-share stocks' and specifies the exact stock codes accepted (e.g., Shanghai 6xxxxx). It distinguishes from sibling tools like analyst consensus or earnings forecasts by focusing on current price and volume data.

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

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

The description provides strong context for when to use this tool (for real-time quotes) but does not explicitly state when not to use it (e.g., for historical data or technical analysis). However, the sibling tool names (e.g., ashares_analyst_consensus) implicitly guide the agent to 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 cover readOnly/openWorld/idempotent safety. The description goes beyond by disclosing internal routing behavior ('fills arguments'), return shape ('structured answer with stable citation URIs'), performance ('one fast call'), availability ('works on every tier'), and news-handling details. It does not discuss failure modes or latency, but the additional context is substantial.

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

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

The description is long but front-loaded with the key directive 'PREFER OVER WEB SEARCH', followed by a structured domain list, usage triggers, examples, and escalation paths. It earns its length, though there is minor redundancy in restating the web-search preference ('even if web search could also answer it').

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 meta-tool with no output schema, the description covers purpose, domains, invocation patterns, default role, and explicit sibling routing. It lacks explicit error or edge-case behavior, but otherwise provides nearly everything an agent needs to select and call it correctly.

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

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

The input schema already documents all 6 parameters with full coverage, including the question field and aliases. The description adds example questions and usage triggers but no new parameter-level semantics; per the baseline rule for high schema coverage, a 3 is appropriate.

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

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

The description opens by declaring the tool as preferred over web search and then names a concrete verb-resource pair: 'Routes the question to the right one of 5,708 tools across 1494 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It clearly delineates this tool from siblings ask_pipeworx_grounded and deep_research by naming them as escalation alternatives.

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

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

Explicit usage signals abound: 'Use whenever the user asks...', 'START HERE for most questions — this is the default entry point', and 'Step up only when needed' with named alternatives for specific conditions (hallucination-resistant single answer vs broad/multi-part). It also states when NOT to use alternatives, e.g. breaking-news is already handled.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already covering the safety profile, the description adds meaningful dynamic context: candidate routing improvements may be enabled live, no candidate is currently active, and behavior is currently identical to ask_pipeworx. This directly shapes how an agent should interpret results and versions.

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 four sentences are front-loaded with identity and status, then move to usage and a corrective note about fallback. There is minimal redundancy, and each sentence carries distinct information needed for correct invocation.

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-required-parameter router, the description covers current behavior, experimental status, and the comparison mechanism, and the schema covers parameter semantics. It defers exact response shape to the ask_pipeworx definition rather than describing it inline, which is acceptable given sibling context but leaves a small completeness gap.

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 all six parameters are documented as aliases for the required question field. The description only repeats that arguments are the same as ask_pipeworx and does not add formatting, length, or example guidance beyond the schema, 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 identifies the tool as the beta version of ask_pipeworx and as a universal router over 5,708 tools, which conveys that it takes a natural-language request and dispatches it to the appropriate tool. It distinguishes itself from siblings by its experimental routing edge and current identity with the stable router, though 'universal router' is still somewhat jargon-dependent.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, which is a clear when-to-use condition. It also states that results are compared against the stable router for merge decisions and clarifies that it is a full working router rather than a stubbed fallback.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), description discloses refusal reasons, evidence extraction, verbatim quoting, and extra LLM call cost. 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?

Every sentence earns its place: purpose, mechanics, success/refusal contracts, usage guidance, and cost tradeoff. Information-dense yet front-loaded with the core value proposition.

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

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

No output schema exists, but description fully documents return payload and refusal reasons. Usage, cost, and safety are covered. Nothing needed for invocation is missing.

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

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

Schema description coverage is 100% — question and its aliases are fully documented in the input schema. Description adds no parameter-specific detail beyond what schema provides, so baseline 3 is appropriate.

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

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

Description states a specific purpose: hallucination-resistant answer mode for high-stakes reads, explicitly extracting answers only from tool results. It names the sibling ask_pipeworx, distinguishing grounded vs casual mode. Clear verb and resource.

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

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

Provides explicit when-to-use (quoted/cited/acted-on answers, must not invent facts) and when-not-to-use (prefer ask_pipeworx for casual lookups) with cost rationale. Alternates and exclusion conditions are unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds extensive behavioral details: workflow steps (resolve, classify, fan out), response shapes, resolver contract, parent event extractor, news fallback fields, safety short-circuits, wide-spread warnings, and resolution-rule risk. This far exceeds 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 very long and includes many examples and edge cases. It is front-loaded with the main purpose but becomes dense. While thorough, it could be more structured (e.g., bullet points) to improve readability. Still, every sentence serves a 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 parameters, no output schema, many behavioral nuances), the description covers all necessary aspects: input formats, behavior for different market types, response structure, safety mechanisms, and resolution rules. An agent can fully understand tool behavior without external references.

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 significant meaning: it clarifies the market parameter can be a slug, URL, or question text; explains depth (quick vs thorough) and include_raw (summarized vs full payload) with practical implications. This adds value beyond the schema descriptions.

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

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

The description opens with a clear verb+resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also lists explicit use cases ('should I bet on X', etc.), differentiating it from sibling tools like polymarket_arbitrage or 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?

The description provides explicit use cases and detailed examples of when to use the tool. It covers edge cases (closed markets, low-confidence matches) but does not explicitly state when NOT to use it. However, the context given is sufficient for an 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 already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds specifics: it pulls 10-K revenue/income/cash/debt for companies and FAERS/trial data for drugs, sorts results by primary metric, handles off-calendar fiscal years, and returns citation URIs. This provides valuable behavioral context beyond annotations.

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

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

The description is somewhat lengthy but well-structured, front-loading example triggers and key instructions. Every sentence serves a purpose, though some minor redundancy could be trimmed. It efficiently conveys the tool's value and operation.

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

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

Despite lacking an output schema, the description states it returns paired data with citation URIs, which sufficiently informs the agent about the response format. For a tool with only two parameters and clear data sources, the description covers all necessary context for correct usage.

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

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

With 100% schema coverage, the description still adds significant meaning: it explains the data sources for each type (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), specifies the format for values (tickers/CIKs for company, drug names for drug), and gives examples. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call, with explicit example triggers like 'X vs Y' and 'rank these companies'. It distinguishes itself from siblings by claiming it replaces 8-15 sequential lookups, making its purpose unmistakable.

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

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

The description instructs to ALWAYS PREFER this tool over sequential single-pack lookups, provides example queries and constraints (max 5 entities, specific types). However, it does not explicitly state when not to use it, such as when more than 5 entities are needed or when different financial metrics are required.

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

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

Annotations provide read-only, open-world, idempotent safety, and the description layers on account/plan requirements, expected latency, gap recovery, contradictions[], hop fields, citation resolvability, and semantic excerpting. 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?

Dense but front-loaded with the account requirement and sibling fallback. A few points are made twice (citation format, not open-web), yet given the tool's many caveats the length is largely earned.

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 findings packet, gap/citation/contradiction behavior, timing, prerequisites, and alternative routing. An agent has enough to invoke it correctly and 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?

Schema-description coverage is 100%, so schema already documents both parameters. The description adds behavioral nuance for depth levels (re-angles gaps, chases leads) and clarifies that 'question' is intentionally broad/multi-part, which exceeds the baseline.

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

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

States a precise operation: grounded multi-source research across 1,494 structured data sources in one call, decomposing the question into facets and routing to 5,708 tools in parallel. Explicitly contrasts with open-web search and distinguishes itself from ask_pipeworx, so sibling differentiation is clear.

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?

Gives explicit when-to-use: broad/multi-part structured questions. Names alternatives: ask_pipeworx for single lookups and for breaking/current-news topics, plus a fallback when not signed in. This leaves little to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by noting that returned tools are 'ready to call directly, no second schema lookup needed', which assures the agent of convenience and immediate usability.

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

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

The description is concise (4 sentences), front-loaded with purpose and use case, and contains no redundant information. Every sentence serves a clear function.

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

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

For a discovery tool with no output schema, the description covers purpose, usage timing, return contents, and examples. It lacks details on error handling or pagination, but for this tool's simplicity, the coverage 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 description coverage is 100%, so the schema already documents all parameters and aliases. The description does not add significant meaning beyond the schema, merely reiterates that the query is natural language. 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 the tool as a tool discovery mechanism, using strong verbs like 'Find', 'browse', 'search', 'look up', and 'discover'. It explicitly differentiates from sibling tools by stating it returns tool definitions ready to call, which is a unique purpose.

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

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

The description provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and implies it should be a preliminary step before selecting a specific tool.

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

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

Beyond annotations (readOnly, idempotent, not destructive), the description details data sources (SEC, XBRL, USPTO, news, GLEIF), return fields, and limitations (patents soft-fail, no names). No contradiction with annotations.

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

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

The description is well-structured with examples first, then preference, then enumerations. It is slightly long but every sentence earns its place; minor trimming possible.

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

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

Despite no output schema, the description fully explains return values (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and the soft-fail for patents, making it complete for agent invocation.

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

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

With 100% schema coverage, the description adds meaning by clarifying value accepts ticker or zero-padded CIK and reiterates that names are not supported, providing clear examples. This exceeds baseline expectations.

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

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

The description clearly states the tool provides a holistic profile of a US public company by aggregating data from multiple sources in one parallel call, distinguishing it from siblings like resolve_entity and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views and warns that names are not supported, advising use of resolve_entity first. This guides appropriate tool selection.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data but doesn't elaborate on other side effects. 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 clear sentences, front-loaded with action and usage context, 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?

Tool is simple (one required param, no output schema). Description covers purpose, usage, and pairing, which is fully adequate for an agent to invoke correctly.

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

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

Schema has 100% coverage with parameter 'key' described as 'Memory key to delete'. Description adds no additional parameter details beyond schema.

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

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

Description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' through the delete action.

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

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

Explicitly mentions when to use: context stale, task done, clear sensitive data. Also suggests pairing with 'remember' and 'recall', though it doesn't specify 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context by explaining the fetch/extract/emit behavior and that output is a single text blob for site-root/llms.txt, though it omits potential timeouts or failures.

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

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

The description is concise (three sentences) and front-loaded with the main purpose. It could be more structured but is appropriately sized and wastes no 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 two parameters and no output schema, the description covers the purpose, parameters, output format, and use cases. It lacks error handling details but is largely complete for typical usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by providing context (e.g., 'Full URL of the site to summarize') and specifying defaults for max_links (25, max 50), going beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the actions (fetches page, extracts title/description/key links, emits markdown) and the purpose (AI crawler indexing). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on file generation.

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 (client site indexing, personal project, competitor audit) but does not mention when not to use this tool or provide alternatives, which is acceptable given sibling tools are mostly unrelated.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context by specifying the return fields (id, type, params, created_at, last_fired_at, fire_count) and the intended use case, which goes beyond what annotations alone 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 only two sentences with no wasted words. The first sentence states purpose and return values, the second provides usage context. Every sentence earns its place.

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

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

For a simple list tool with one optional parameter and comprehensive annotations, the description covers purpose, return fields, and usage. No additional details are needed.

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

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

The input schema has one parameter with a full description, and schema description coverage is 100%. The tool description does not add additional meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'subscriptions', and the scope 'caller's active'. It also lists the return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly says when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel'. It does not explicitly state when not to use it, but the context from sibling tools makes it clear.

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

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

Annotations only set all hints to false, providing little signal. The description compensates by disclosing rate limits ('Rate-limited to 5 per identifier per day'), the claim_token flow (returns token, pass it back later to read status), and that it is free and doesn't count against quota. It also clarifies output behavior for claim_token lookup.

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

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

The description is longer than ideal but every sentence adds a distinct point (purpose, use cases, scope boundary, claim_token flow, rate limit, quota). It is front-loaded with the primary purpose and structured to cover common questions, making it efficient for an agent despite its length.

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

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

Given there is no output schema, the description must explain return behavior on its own. It does so clearly: filing without an account returns a claim_token, and later passing that token with no other args returns status and resolution details. It also covers rate limits and the tool's free/quota-free nature, making it complete for an agent to invoke correctly.

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

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

Schema covers all parameters with descriptions, so baseline is 3. The description adds value by explaining the claim_token lifecycle ('pass it back later') and offering guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This is meaningful extra context.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this feedback tool from sibling tools like ask_pipeworx or discover_tools by focusing on reporting issues and praise, not asking questions or discovering tools.

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

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

The description gives explicit when-to-use guidance for each category (bug, feature/data_gap, praise) and an explicit exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' Also includes a fallback hint for uncertainty.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: data source (CF analytics-engine), privacy (no PII), data structure (pack, tool, count), and caching behavior (5min-1h). No contradictions with annotations.

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

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

The description is concise: two sentences plus a bullet list. Every sentence adds value—purpose, use cases, technical details. Front-loaded with the core functionality. No redundant wording.

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

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

Given the simple input (one optional parameter, no output schema), the description covers purpose, usage, behavior, and data source well. The only minor gap is that it doesn't specify exact output format (e.g., structure of the response), but it is sufficient for an agent to decide when to call.

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 the single parameter (window) with enum and description. The tool description adds additional semantics by explaining that shorter windows show current hotness and longer windows show steady-state demand, which complements 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 'Returns the top tools, top packs, and total call volume over a recent window' and lists three specific use cases. It clearly distinguishes itself from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on aggregate trending data rather than individual queries.

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

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

The description provides three concrete scenarios for when to use the tool (discovery, confirmation, alignment check), which gives excellent context. However, it does not explicitly state when NOT to use it or name alternative tools for specific cases.

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

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

Annotations already indicate read-only, but description adds extensive behavioral details: monotonicity checks, partition-sum checks, Jaccard similarity filter, placeholder filter, fill check with book depth. 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?

Dense but well-structured: overview sentence, then mode details, then special checks. Every sentence provides necessary context. Could be slightly more concise but overall effective.

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

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

Given complexity and no output schema, description covers response structure (opportunities[] with gap_pp, suggested_trade, etc.), fill check, and edge cases (placeholders, similarity). Minor omission of explicit field list, but sufficient for agent to understand outputs.

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 each parameter's purpose in context (e.g., event slugs vs seed questions), behavior of modes, and acceptance of full URLs. Exceeds baseline.

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

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

Clearly states it 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and distinguishes three modes (no args, event, topic). Differentiates from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. Also references sibling tool polymarket_fill_risk for custom sizing. Lacks explicit when-not-to-use but still clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds extensive behavioral context: five model families, caching (1h KV), response structure, edge components, filtering knobs, and diagnostics. 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 well-structured with clear sections and front-loaded purpose. Every sentence contributes value, though it could be slightly more concise for a scanning tool. 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?

Given the complexity (9 parameters, no output schema), the description fully covers purpose, usage, parameter semantics, behavioral details, response structure, and diagnostics. It explains edge cases like Fed signals and why segments might be empty, making it self-contained for an agent.

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

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

Schema coverage is 100%, but the description adds significant value beyond schema defaults and descriptions. For example, explains slippage_pp with Polymarket fee context, min_kelly as half-Kelly fraction, and tradeable-edge filters with practical guidance (e.g., set min_liquidity to 5000).

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb+resource. It distinguishes from siblings like polymarket_arbitrage by its focus on edge opportunities with detailed model families.

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

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

The description explicitly targets 'what should I bet on today' use case and mentions not paging hundreds of markets. It provides knobs for filtering but does not explicitly exclude alternatives or state when not to use this tool versus siblings like polymarket_arbitrage.

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

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

Annotations already mark it as read-only and idempotent. Description adds that it reads snapshots, limits history to 60-day TTL and snapshot enablement start, and that decay numbers come from daily closes not intraday. No contradictions.

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

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

Description is detailed but well-structured, with core purpose first, then parameter details, response format, and limitations. Could be slightly shorter but each sentence adds value.

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

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

Given no output schema, description fully explains the three response arrays (tracked, expired, snapshot_dates) with their fields and semantics. Also covers limitations (TTL, start time, intraday vs daily). Adequate for the tool's complexity.

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

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

Schema covers 100% of parameters with descriptions. Description adds context: default values (14 days, '1wk'), clamp for days (2-30), and explanation that window selects snapshot family. Provides meaning beyond schema for use in the telemetry context.

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

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

Describes the tool as providing 'edge persistence and decay telemetry' built from daily snapshots, answering 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from sibling tools like polymarket_edges by focusing on time-series analysis and decay trends.

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

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

Implicitly states when to use: to understand edge duration and decay, contrasting a fresh wide edge with an old one. Does not explicitly list when not to use, but context implies not for real-time edge detection. Sibling tool names help differentiate.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: explains it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and highlights risks like thin legs and 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?

The description is well-structured with a front-loaded purpose, followed by clear mode explanations and usage guidelines. While slightly verbose, the complexity of the tool (two modes with distinct behaviors) justifies the length. It could be more concise without losing clarity.

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

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

For a tool with no output schema and moderate complexity, the description covers all essential aspects: mode-specific returns (fields listed), edge cases (thin legs, directional risk), and links to sibling tools. Only minor gap is lack of explicit return format for single-market, but overall it's thorough.

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% for all 4 parameters. The description adds value by explaining parameter behavior in each mode (e.g., 'size_usd interpreted as settlement notional S' for basket, side default auto from partition sum). Since schema already covers basics, the description supplements well, justifying above baseline 3.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' and distinguishes between single-market and basket modes. It explicitly differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating to use this before acting on their signals.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns that partial basket fills convert an arb into an unhedged directional position, providing clear when-to-use and when-not-to-use guidance.

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

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

Even with strong annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial behavioral detail: compatibility_warning and compatibility_codes can be non-empty even when matched_pairs > 0, unknown legs are never paired, skip counters explain dropped comparisons, and temporal alignment is reported. No statement contradicts 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 long and dense, but the length is largely justified because there is no output schema and the tool has complex safety semantics. It is front-loaded with the core purpose, and most sentences carry functional information, though bulleted sections would improve 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?

With no output schema, the description carries full responsibility for explaining the response shape, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, low_confidence_pairs, skipped_unclassified, temporal_alignment, and skip counters. It also covers all parameter modes and provides necessary cautionary guidance.

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

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

The schema already covers all three parameters at 100%, so the description's parameter role is additive rather than essential. It adds useful context about the topic mode auto-fetching matching events and the explicit mode enabling custom pairings, but some topic-value detail duplicates 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 opening line defines a specific computation: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It narrows the scope further with two modes and the Kalshi-minus-Polymarket sign convention, which clearly differentiates it from single-venue or general arbitrage tools.

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

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

The description explicitly distinguishes the two operating modes — 'topic' shortcuts versus explicit ticker/slug pairings — and explains when each is appropriate. It also warns that pre-mapped topics often return compatibility warnings and that pre-mapped is not tradeable, though it does not name sibling tools or provide an explicit when-not-to-use alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behaviors. The description adds scoping information (per identifier) and the dual behavior when key is omitted vs provided, which provides useful behavioral context beyond annotations.

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

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

The description is two sentences, front-loads the core action, and uses no extraneous words. Every sentence adds value.

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

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

The tool is simple with one optional parameter. The description covers functionality, scoping, and associated tools fully. No output schema is needed as the return behavior is implied by the description.

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

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

Schema coverage is 100% and already describes the key parameter and its omission behavior. The description adds examples of typical key values but does not significantly enhance parameter understanding 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 verb (retrieve/list), resource (saved memory values/keys), and distinguishes from siblings by naming remember and forget. Examples of use cases (ticker, address, research notes) further clarify purpose.

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

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

The description explains when to use the tool (to look up stored context without re-deriving) and how it pairs with remember/forget. It does not explicitly state when not to use it, but the context is clear enough.

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

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

The description discloses behavioral traits beyond the annotations: it explains that setting mark_read:true flags events as read so the next call only shows newer ones, and that polls work fine. This adds context to the readOnlyHint and idempotentHint annotations.

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

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

The description is concise with four sentences, each adding value. It front-loads the purpose and avoids redundancy or fluff.

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

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

With no output schema, the description explains the return structure (source, citation_uri, raw payload) and all filtering options. It also covers behavioral aspects like mark_read and polling suitability, making it complete for a simple retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the effect of 'mark_read' ('so the next call only shows newer ones') and clarifying the 'limit' default and range, though the schema already includes these. This extra context justifies a 4.

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

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

The description starts with 'Pull fired events from your subscription feed,' clearly stating the tool's specific verb and resource. It distinguishes itself from sibling tools like 'ask_pipeworx' or 'recent_changes' by focusing on fired events from a persisted feed.

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 that polling works fine and provides an alternative URL for scripts/dashboards, but it does not explicitly state when to use this tool versus alternatives among the many sibling tools. No exclusions or comparisons are provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. Description adds value by detailing multi-source fan-out, fallback behavior (GNews when GDELT rate-limited), API sunset for USPTO, and output format with citation URIs. 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?

Front-loaded with example queries, then detailed technical explanation. Every sentence serves a purpose—no filler. Length is justified given the tool's complexity.

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

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

Without an output schema, description fully explains return format (changes grouped by source, total_changes, pipeworx:// URIs) and error handling (patents soft-fail). Covers multiple input types and fallback behavior, making it 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 covers all 3 parameters with descriptions. The description adds context for 'since' (ISO date vs relative shorthand examples) and typical value '30d', enhancing 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?

Description clearly states it's a change feed for a company in a time window, with specific example queries like 'What's new with X' and 'latest on Y'. It distinguishes from sibling entity_profile by contrasting use cases.

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 mentions when to use entity_profile instead. However, it doesn't elaborate on scenarios where this tool should be avoided beyond the sibling 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?

Discloses scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours). Annotations already indicate idempotentHint=true and destructiveHint=false; description adds valuable context 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?

Single paragraph, front-loaded with purpose, no unnecessary words. Every sentence adds value, including usage guidance and pairing with other tools.

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

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

For a simple key-value store, the description covers purpose, behavior, scoping, persistence, and companion tools. No output schema exists, and the description does not need to explain return values as it's a write-only action.

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 description adds limited new information. However, it provides concrete examples for key naming conventions (e.g., 'subject_property', 'target_ticker') and clarifies value is arbitrary text, which aids usage beyond schema definitions.

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

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

Description clearly states the tool saves data for reuse across conversations, using specific verbs 'Save data' and resource 'key-value pair'. It distinguishes from siblings by mentioning 'recall' and 'forget' explicitly.

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

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

States when to use: when discovering something worth carrying forward. Mentions companion tools recall and forget. Lacks explicit 'when not to use', but context is clear enough.

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

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

The description reveals rich behavioral details: cascading through multiple endpoints, graceful degradation when external sources are unavailable, explicit labeling of unresolved identifiers, and ISIN-to-LEI mapping for non-US issuers. This goes well beyond the readOnly/idempotent annotations and provides genuinely useful execution context.

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

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

The description is lengthy but purposefully structured. It leads with relatable query examples, then states the primary directive, then details supported types and behavioral nuances. Every sentence carries practical information with no filler or repetition, so conciseness remains high despite length.

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

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

Given there is no output schema, the description compensates by describing the return structure: source labels, unresolved array, parent/ultimate-parent/children ownership data, and graceful degradation. This gives the agent sufficient understanding of what to expect from the call without over-specifying.

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 property descriptions are clear. The description adds semantics by extending accepted value formats (e.g., ISIN for company) and explaining the returned identifier types (RxCUI + ingredient + brand for drugs). This is valuable, though the schema already does much of the heavy lifting.

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

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

The description explicitly states the tool's function: resolving user-spoken names to canonical/official identifiers such as CIK, LEI, RxCUI, etc. It includes concrete query examples and distinguishes itself as the necessary first step for ID lookup, contrasting with sibling tools like compare_entities and entity_profile.

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?

Usage guidance is explicit: 'Use FIRST whenever you have a name but need an ID.' It also documents supported types and input forms. However, it does not explicitly say when not to use the tool or name alternative tools for scenarios like full entity profiling, so it falls short of a perfect score.

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

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

Annotations already indicate read-only, non-destructive, idempotent, and open-world. Description adds behavioral details: probes each entity with ai_visibility_check, ranks, and treats first entity as subject. 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?

Four sentences with no fluff. Main action first, then method, use case, and output. Every sentence earns its place.

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

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

Given 4 params with full schema, annotations, and no output schema, description sufficiently covers output format (ranked list with score, confidence, signal density) and constraints (2-8 entities, first is subject).

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. Description adds meaning: first entity is subject, models default to workers-ai, _apiKey only needed for anthropic. Adds value beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities, ranks by score, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check by specifying multi-entity comparison.

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

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

Provides context of competitive AI-marketing audits and an example question. Implicitly differentiates from single-entity tool ai_visibility_check, but lacks explicit when-not-to-use or alternative tool mentions.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are complemented by description details: fans out across services, partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed lists timeouts. No contradictions.

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

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

Description is a single paragraph but every sentence delivers useful information. Could be slightly more structured (e.g., bullet points for return fields), but no filler words. Efficient despite length.

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

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

No output schema, so description must explain return values. It lists summary fields, advisory details, links, and alternative versions. Also covers failure modes. Comprehensive for the tool's complexity.

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

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

Schema description coverage is 100% for both parameters (package and version). Description adds context on default version (latest) and scoped packages accepted, which adds modest value beyond schema. Baseline 3 increased to 4 for helpful extra nuance.

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 is a composite check for npm packages across deps.dev and bundlephobia, answering 'should I add this package'. It specifies verb 'scan' and resource 'dependency', and implicitly distinguishes from financial and research siblings by focusing on package analysis.

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

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

Explicitly tells when to use: 'when an agent asks is X safe/popular/small or what does adding lodash cost me'. Also specifies exclusion: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly', guiding agent to alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: embedding model (BGE-base-en), overlapping 500-char windows, 200K char cap with truncation and flagging, and character offsets in output. 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 concise yet comprehensive, covering purpose, usage, technical details, and pairing. Each sentence adds value, and the structure flows logically from what it does to how it works.

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

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

Despite no output schema, the description explains return values (passages with offsets and scores). It covers input constraints (200K chars), truncation behavior, and workflow integration with sibling tools. For a 3-parameter tool, this is highly 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?

The input schema already fully describes all 3 parameters with clear descriptions (100% coverage). The description provides extra context like query examples and confirms the 200K char limit for text, adding marginal 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 performs semantic search inside a fetched record, with concrete examples like SEC 10-K and article. It distinguishes itself from siblings by specifying it works on already-fetched text and pairs explicitly with ask_pipeworx_grounded.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and advises pairing with ask_pipeworx_grounded for a grounded response. It also explains that returned passages have offsets for verification, guiding appropriate usage.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds important behavioral context: phone verification requirement, SMS cap of 10/day, webhook auto-disable after 10 failures, and that the webhook secret is returned once. However, the idempotentHint=true annotation is not explained or supported by the description, which suggests each call creates a new subscription. This gap prevents a score of 5.

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

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

The description is detailed yet concise, with the core purpose front-loaded. Every sentence adds substantive information, such as requirements, type examples, and delivery details. There is no redundancy or filler text. It efficiently communicates all necessary context.

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

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

For a tool with 3 parameters (including a nested object), no output schema, and significant complexity, the description is remarkably complete. It covers the return value (subscription id), all parameter semantics with examples, account prerequisites, delivery channel nuances, and failure behavior. No obvious gaps remain.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds considerable value beyond the schema: it provides concrete examples for each subscription type, clarifies constraints (phone verification, SMS cap, webhook requirements), and explains the delivery channel behavior. This greatly aids the agent in constructing correct invocations.

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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like 'list_subscriptions' (listing) and 'unsubscribe' (removing). The verb 'create' and resource 'subscription' are specific.

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

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

The description explicitly requires a Pipeworx OAuth account, implying it should not be used by anonymous users. It lists supported types and delivery channels. While it does not explicitly state when not to use, the context from siblings and requirements provides clear guidance. A score of 4 is appropriate for lacking explicit exclusion 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 indicate readOnlyHint, idempotentHint, and destructiveHint false. Description adds that it returns response structure (example questions with tool/argument shape). No contradictions, but could add more about idempotency or side effects.

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?

Front-loaded with common queries and structured explanation. Slightly verbose but every sentence adds value. Could be trimmed slightly without losing clarity.

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

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

For a simple tool with one optional param, no output schema, and strong annotations, the description fully explains purpose, usage, and expected output. No gaps.

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

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

Schema covers 100% of the single parameter, but description enriches by listing actual topic values (finance, pharma, etc.) and clarifying that omitting topic gives full spread. This adds meaningful guidance beyond schema description.

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

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

Description clearly states the tool's purpose: returning category-bucketed example questions and meta-tool calls. Distinguishes from siblings like ask_pipeworx and discover_tools by positioning itself as the onboarding entry point.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains how to call with or without topic parameter. Provides clear context for when to use and what alternatives (e.g., meta-tools) are.

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

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

Adds significant detail beyond annotations: ownership enforcement, deactivation vs deletion, impact on recent_alerts. 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?

Three sentences, front-loaded with purpose, each sentence provides essential information without 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, description covers purpose, ownership, and side effects adequately. Could mention error handling but not critical.

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

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

Schema coverage is 100% with parameter description, and tool description adds no new information about the parameter beyond what schema already provides.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id', distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Provides clear context on ownership enforcement and effect (deactivation vs deletion), implicitly guiding when to use. Does not explicitly name alternatives but is sufficient given sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral context: the six verdict types, the critical meaning of could_not_verify versus unsupported, the verification_error payload, and the fact that this replaces multiple sequential calls. It does not contradict any annotation.

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

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

The description is dense but well-structured: it front-loads query patterns and core purpose, then adds verdict semantics and caller warnings. Every sentence earns its place, and the length is appropriate for the complexity.

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

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

With only two flat parameters, no output schema, and no nested objects, the description is complete enough. It covers return shape (verdict, value, citation, reasoning), error semantics, source routing, and caller warnings, giving an agent everything needed to select 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%, so baseline is 3. The description adds meaningful parameter semantics: tolerance_pct overrides claim wording, is recommended at 1–2 for hallucination detection, and defaults to wording-derived capped at 5; claim gets concrete examples. This is substantial extra guidance.

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

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

The description opens with natural-language query patterns and states 'natural-language claim verification against authoritative sources.' It clearly identifies the action (verify/validate) and resource (claims), and distinguishes itself from fact-finding siblings by scoping to checking whether a user's statement is factually correct.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and details internal routing for financial vs. other claims. It does not name competing sibling tools or state when not to use it, so it stops short of full alternative guidance.

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