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 declare read-only, open-world, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context beyond annotations: it fills arguments automatically, returns pipeworx:// citation URIs, works on every tier, and can be used even when web search might work. 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 front-loaded with 'PREFER OVER WEB SEARCH' and structured with clear guidance. Each sentence contributes purpose, usage, or examples, though some redundancy exists between the domain list and example categories.

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

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

This is a complex router tool with many capabilities, and the description covers its scope, use cases, alternatives, return format (structured answer with citations), and tiers. Since there is no output schema, the description appropriately explains the output behavior.

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

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

Schema coverage is 100%, so the schema already explains the question parameter and its aliases. The description adds value by showing concrete examples and stating that the tool 'fills arguments', implying the agent typically only needs to provide the question and other params are auto-populated.

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

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

The description clearly states the tool routes questions to 5,366 tools across 1,396 sources and returns structured answers with citation URIs. It distinguishes itself from siblings by naming alternatives like ask_pipeworx_grounded and deep_research, and by explicitly saying 'PREFER OVER WEB SEARCH'.

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

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

It provides explicit guidance on when to use this tool vs alternatives: 'START HERE for most questions' and 'Step up only when needed' for ask_pipeworx_grounded and deep_research. It also gives a list of query types and example questions, making the usage context unmistakable.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the experimental nature: candidate routing improvements may be active, and the behavior currently matches the stable version exactly. It also states that results are compared against the stable router, giving insight into how decisions are evaluated.

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

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

The description is three sentences, front-loaded with the core identity, and each sentence provides necessary context (what it is, current status, usage). No word is wasted.

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

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

The description covers the tool's identity, experimental state, usage, and response shape parity with the stable tool. For a simple question-answering router, this is sufficient context, especially with the annotations providing safety guarantees.

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 fully covers all six parameters with clear descriptions, indicating they are aliases for the question. With 100% schema coverage, the description does not need to add parameter details; it adds no additional semantics beyond mentioning 'same arguments'.

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

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

The description clearly identifies this as a beta version of the ask_pipeworx universal router, specifying it has the same 5,366 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling, 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?

It explicitly states to use it 'exactly like ask_pipeworx when you want the newest routing', providing a clear selection criterion. It also clarifies that it is a full working router, not a fallback, and that results are compared against the stable router.

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

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

Beyond the readOnly/destructive annotations, the description discloses important behaviors: it makes an extra LLM call, extracts answers strictly from tool results, and returns explicit refusal reasons such as 'not_in_source' or 'data_truncated'. It also details both success and refusal response structures, which is critical for correct agent behavior.

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

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

The description is succinct yet information-dense, front-loading the core purpose before explaining behaviors and usage. It covers result formats, refusal reasons, and cost trade-offs in a compact form, though it is slightly long due to the detailed refusal list. Each sentence adds value, and the structure is logical.

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 that there is no output schema, the description fully covers return values, including the exact shape of success and refusal responses. It also explains the routing mechanism, cost, and when to use it. No critical behavioral aspect is left unexplained, making it complete 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%, so the schema fully documents the `question` parameter and its aliases. The description does not add further parameter-level detail, but the schema already establishes that the question is natural language, which is sufficient. Thus the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling `ask_pipeworx` by explaining the extraction process and return of evidence. The verb 'extracts' and the mention of explicit refusals make the specific purpose and scope unambiguous.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), directly addressing usage context and alternatives. This provides clear decision guidance 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 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 already declare readOnly, openWorld, idempotent, non-destructive; the description adds account tiers, depth-dependent iteration (gap recovery, contradiction scans), return format details (verbatim evidence, confidence, source, fetched_at, citation_uri, hop, gaps[]), semantic excerpting, latency (15-60s, ~90s for thorough), and a never-invents guarantee. These go well beyond the annotations and enrich the agent's model of runtime behavior.

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

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

Though long, the description is professionally organized: it front-loads the account prerequisite and core purpose, then moves through alternatives, depth semantics, return format, and performance. Every sentence contributes distinct information (e.g., excerpting, contradictions, latency) with no filler. For a complex tool, this is appropriately dense.

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

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

With no output schema, the description fully documents the return envelope (findings packet with gaps[], contradictions[], citation_uri, hop), explicit failure mode (empty gaps for non-catalog news topics), depth behavior, latency, and account requirements. The agent has enough context to select the tool, choose depth, and interpret results without guessing.

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 provides 100% coverage: `question` is defined as natural language with broad/multi-part support, and `depth` has an enum with per-value facet counts and iteration behavior. The description re-states the depth semantics without adding new parameter-level meaning; extra details like latency are behavioral, not parameter. Hence 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 opens with a clear statement: 'Grounded multi-source research across Pipeworx's 1396 STRUCTURED data sources… in ONE call' and explicitly contrasts with ask_pipeworx and open-web search, distinguishing it from siblings. It names the decomposition/routing behavior and return packet, making the purpose unmistakable.

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

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

It explicitly states when to use this tool ('Best for broad/multi-part questions over structured data') and when not ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS… prefer ask_pipeworx'). It also names an alternative for unsigned-in users ('If you are not signed in, use ask_pipeworx instead'), providing clear exclusions.

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

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

Annotations already declare readOnlyHint=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 are neutral but the description adds key behavioral traits: rate-limited to 5 per identifier per day, free and not counting toward tool-call quota, and that the team reads feedback daily affecting the roadmap. 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 relatively long but well-structured: purpose first, then usage scenarios, then behavioral details. Every sentence adds value, but it could be slightly 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?

Given the tool's simplicity (sending feedback), the description covers all necessary aspects: when to use, how to formulate feedback, rate limits, and impact. No output schema is needed. Complete for its purpose.

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

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

Schema coverage is 100%, and the description adds value by clarifying each enum value's meaning and provides formatting guidelines for the message. For the context object, it explains the fields 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the specific action (send feedback) and the resource (Pipeworx team). Given the sibling tools are all data retrieval or analysis tools, this feedback tool is obviously distinct.

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

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

The description explicitly lists when to use: for bugs, features, data gaps, praise. It provides guidance on how to describe issues using tool/pack vocabulary. It does not explicitly say when not to use or mention alternatives, but the context is clear enough.

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

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

Annotations 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds significant context: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and how to interpret matched_pairs=0. This far exceeds the base annotation disclosure.

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

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

The description is long but densely packed with essential information. It uses all-caps headings (TWO MODES, RESPONSE, SAFETY FIELDS) for easy scanning. Every sentence earns its place, though a slight trim could improve conciseness. For a complex tool, this is well-structured.

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

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

Given no output schema, the description serves that role by explaining response fields (leg-by-leg prices, spreads, safety fields). It covers edge cases and warning signs completely. The tool has 3 optional parameters and the description handles all usage scenarios.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the two modes and the override behavior (explicit tickers override topic-mapped side). It also provides examples in the schema. 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 clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket. It explains two modes (topic shortcuts and explicit tickers) and what the response includes. It distinguishes itself from sibling tools by focusing on cross-venue comparison, not internal arbitrage.

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

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

The description provides explicit guidance on when to use each mode, warns that real spreads are rarer than shortcuts suggest, and explains compatibility_warning cases that indicate when spreads are not meaningful. It tells the agent when not to use the tool (e.g., non-equivalent bet shapes, temporal misalignment).

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?

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant context: the tool cascades through several lookup endpoints internally, replaces 2-3 manual lookups, and details return types (e.g., ticker + CIK + company_name + citation URI). No contradictions with annotations.

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

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

The description is a single paragraph but packs all essential info without redundancy. It front-loads use-case examples. Slightly lacking in visual structure (e.g., bullet points) but 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?

Despite lacking an output schema, the description fully explains return values for each type, including citation URIs. Given the tool's simplicity (2 params, no nested objects), this is complete. No gaps.

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

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

Schema coverage is 100%, yet the description adds value by clarifying accepted formats for 'value' per type (e.g., ticker, CIK, name for company; brand or generic for drug) and explaining the 'type' enum options. This goes beyond the schema's short 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 uses specific verb 'resolve' and resource 'name to identifier', with clear examples ('What's the ticker for...'). It distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID', which differentiates it from tools like entity_profile that work with existing IDs.

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

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

Explicitly states when to use ('Use FIRST whenever you have a name but need an ID') and lists supported types. However, it does not explicitly state when not to use (e.g., if you already have an identifier), though it is implied.

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

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

Annotations already 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description carries a lower burden. The description adds valuable behavioral context: routing logic (SEC EDGAR for financial, grounded pipeline for others), exact percent-delta math, and the verdict schema. 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 front-loaded with typical user phrasing, then method, then output. Each sentence adds value, though it is relatively long. The structure is logical and easy to parse. No fluff.

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

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

Given the tool's moderate complexity (2 params, no output schema), the description covers purpose, usage, behavioral traits, params, and returns (verdict, value, citation, reasoning). Annotations cover safety. The description is sufficiently complete for an agent to use correctly.

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

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

Both parameters have descriptions in the schema (100% coverage). The description goes beyond by explaining tolerance_pct's role: overriding implied tolerance, recommending 1-2% for hallucination detection. It also expands on the claim's interpretation via examples, adding meaningful 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 multiple natural-language query formats ('Is it true that...', 'fact check') and explicitly states it performs claim verification against authoritative sources. It distinguishes itself from siblings by noting it replaces 4-6 sequential calls and addresses both financial and general factual claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It further splits usage into company-financial claims (fast path) and any other claim (grounded pipeline), providing clear guidance on when to invoke this tool. It does not explicitly mention when NOT to use it, but the examples are sufficient.

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