Shibui Finance

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

Annotations already provide destructiveHint=true, and the description adds details about the output format (branded headers, smart formatting, auto-fit columns). It does not elaborate on exactly what is destroyed, but the context is adequate.

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 main purpose, and each sentence adds value. No redundant or unnecessary words.

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

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

Given the tool's simplicity (2 parameters) and presence of an output schema, the description sufficiently covers the tool's function and output characteristics without needing to explain return values.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description does not add significant new meaning beyond mentioning that query is the same as stock_data_query, and giving an example for title.

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 exports query results to a branded Excel spreadsheet, and distinguishes itself from stock_data_query by specifying it returns a downloadable Excel file instead of raw 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 contrasts with stock_data_query, indicating when to use this tool (for Excel output) versus the sibling. However, it does not explicitly state when not to use it or other alternative tools.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds non-contradictory context about being required and authoritative, and that it must be called first. This enriches behavioral understanding without redundancy.

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

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

The description is front-loaded with the most critical information in all caps, and each sentence adds value. However, it is somewhat lengthy; a slightly more concise version could be even better.

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

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

Given no parameters and presence of an output schema, the description is comprehensive. It explains the tool's purpose, usage constraints, prerequisite role, and scope (9,500+ companies, 64 years of data), providing a full picture for the agent.

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

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

The tool has no parameters, so the description needs no parameter details. Schema coverage is 100% as there are no parameters. Baseline score of 4 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 loads the database schema for US stock/financial queries, establishing it as the authoritative source. It explicitly distinguishes itself as a prerequisite, setting it apart from sibling tools.

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

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

The description provides explicit usage guidance: it must be called once per session before using stock_data_query or any workflow tool, and after it returns, call get_query_patterns. It lists specific use cases (stock prices, earnings, etc.) making it clear 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?

Beyond annotations (readOnly, idempotent), the description explains that the tool contains query patterns that are critical for correct time-series queries, and that it must be called in a specific order. This adds valuable behavioral context.

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

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

The description is concise and front-loaded with the most critical information (required, when to call). Every sentence adds value, and the structure is clear and easy to parse.

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

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

Given the tool has no parameters and an output schema exists, the description adequately covers what the tool does, why it's needed, and how it fits into the workflow. No additional information is necessary.

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?

There are no parameters, and schema coverage is 100%. The description adds no param-specific info, but following the baseline for 0 parameters, a score of 4 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's purpose: to load SQL patterns that are required before stock_data_query to prevent timeouts and wrong results. It also specifies the number of patterns (23) and their categories, distinguishing it from sibling tools.

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

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

Provides explicit usage instructions: must be called once per session immediately after get_database_schema and before stock_data_query. It also warns of consequences if not used (timeouts, wrong results), making the usage context very clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe and side-effect-free. The description adds behavioral context by specifying it contains 'hard rules for survivorship bias, outlier handling, sampling design, day-of-week filters, and risk-adjusted metrics.' This goes beyond annotations without contradicting them.

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

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

The description is about six sentences, front-loaded with the main purpose. It efficiently conveys prerequisites and use cases. While the list of user intents is somewhat lengthy, it is necessary for clarity. Overall, it is well-structured but could be slightly more concise.

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

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

For a workflow tool with no parameters, the description is complete. It covers the tool's purpose, usage guidelines, prerequisites, and behavioral details. The presence of an output schema (not shown but indicated) reduces the need to describe return values. The description adequately equips the AI agent to select and invoke this tool correctly.

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

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

The tool has no parameters, so schema description coverage is 100%. Per the rubric, zero parameters results in a baseline score of 4. The description adds no parameter-specific information, which is appropriate since no parameters exist.

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 loads a backtesting analysis workflow, listing specific guardrails and use cases. It effectively differentiates from sibling tools by specifying its domain (backtesting/simulation) and providing a comprehensive list of user intents that trigger this tool.

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

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

The description explicitly states when to use the tool: 'Call BEFORE writing SQL when the user asks to backtest, simulate, validate a strategy...' It also details prerequisites (requires get_database_schema then get_query_patterns first) and notes it can be combined with other workflow tools. This gives clear guidance on invocation order and context.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: dependencies on other tools and combinability. No contradictions.

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

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

Three sentences, each serving a purpose: primary function, prerequisites, and use cases. No wasted words, front-loaded with the core purpose.

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

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

Given zero parameters, an output schema, and clear annotations, the description is fully adequate. It covers what the tool does, when to use it, and prerequisites.

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 in the schema, so baseline is 4. The description adds context about what the workflow does (X vs Y) but doesn't define parameters since none exist.

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 loads a comparison workflow for peer analysis and relative valuation. It lists specific user intents (e.g., 'X vs Y', 'how does X compare to Y') and distinguishes from sibling workflow tools by focusing on comparisons.

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 defines prerequisites: requires get_database_schema then get_query_patterns in order. States when to call (before writing SQL) and when the user asks comparison-related questions. Also mentions combinability with other workflow 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=true, idempotentHint=true, destructiveHint=false. Description adds important behavioral context: ordering requirements and that it's a workflow loader (not just a query), which is beyond what annotations provide.

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

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

Two sentences, front-loaded with purpose, then prerequisites and usage conditions. Every sentence earns its place with no 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?

Given zero parameters, annotations, and output schema existence, the description is fully complete. It covers what the tool does, prerequisites, when to use, and combinability.

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, schema coverage 100%. Baseline 4 is appropriate; description doesn't need to add param info.

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 loads an earnings workflow for specific topics (EPS surprises, beat/miss, estimates, revenue), distinguishing it from sibling workflow loaders that focus on backtesting, comparisons, filings, etc.

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

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

Explicitly lists prerequisites (must call get_database_schema then get_query_patterns in order) and provides clear when-to-use guidance (before writing SQL for earnings-related queries) plus combinability note.

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 confirm read-only, idempotent, non-destructive. The description adds valuable behavioral context: required prerequisites and that it loads metadata (not transaction detail). No contradictions. Slight gap: doesn't explain if loading state persists or is session-scoped.

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?

Concise, front-loaded with purpose, then prerequisites, then usage conditions, then exclusion. Every sentence adds value with no redundancy. Appropriate length for a zero-parameter tool.

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 zero parameters, rich annotations, and an output schema, the description covers purpose, prerequisites, usage scope, and alternatives. Complete for an agent to decide when and how to invoke the 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?

Input schema has zero parameters (schema coverage 100%). Per rubric, baseline 4 for 0 parameters. Description adds no parameter details, but none are needed.

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 (Load) and resource (filing workflow for SEC/EDGAR metadata, 8-K events, 10-K/10-Q reports). It distinguishes from sibling tools like load_insider_workflow by specifying that this tool handles metadata and form type, not transaction detail.

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 prerequisite calls (get_database_schema then get_query_patterns) and order. Provides clear when-to-use conditions ('Call BEFORE writing SQL whenever...') and lists specific triggers. Also tells when to use an alternative (load_insider_workflow for transaction detail).

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), the description emphasizes it is a safe, non-destructive loading operation and enforces a required call sequence, providing useful behavioral context.

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

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

Three sentences: purpose, prerequisites, usage scenarios. Front-loaded and concise, 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?

With no parameters and an output schema present, the description fully covers purpose, prerequisites, and use cases. No gaps.

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

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

No parameters exist, so schema coverage is 100%. The description does not need to add param details; the baseline of 4 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 loads a fundamental analysis workflow covering valuation, cash flow, margins, and balance sheet, distinguishing it from sibling tools like load_technical_workflow.

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

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

Explicit prerequisites are given: get_database_schema then get_query_patterns must be called first. Specific user queries are listed to indicate when to use this tool, and it notes it can be combined with other workflows.

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 value beyond annotations by stating ordering requirements and combinability with other workflows. Annotations already mark it as read-only, idempotent, not destructive—description does not contradict and adds context.

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

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

Front-loaded with purpose, followed by prerequisite and usage triggers. Conveys all necessary info in a few sentences, though could be slightly more concise by removing redundant examples.

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?

Output schema exists (not shown but indicated), annotations cover safety, and description provides prerequisites and usage guidance. Sufficient for the complexity of a workflow loader.

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 in input schema, so schema coverage is 100%. Description does not need to add parameter info; baseline is 4 for zero-param tools.

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 loads an insider workflow and lists specific transaction types (Form 3/4/5, buy/sell, cluster buy, 13D/G). Distinguishes from sibling workflow loaders like load_earnings_workflow.

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 prerequisites (must call get_database_schema then get_query_patterns first) and provides a comprehensive list of when to call the tool (e.g., insider transactions, Form filings, etc.). Lacks explicit when-not-to-use but the triggers are clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations, such as the required call order and that it loads a workflow (not a mutation). It does not contradict annotations.

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

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

The description is fairly concise with front-loaded purpose. However, the first sentence ends abruptly with '...' which slightly undermines clarity. Otherwise, efficient use of sentences.

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

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

Given no parameters and presence of an output schema (as per context signals), the description adequately explains the tool's purpose and prerequisites. It mentions combinability with other tools, adding useful context. Could be more specific about the output, but the schema handles that.

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

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

The tool has zero parameters, so baseline is 4 according to guidelines. The description does not need to add parameter info, and none is provided.

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

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

The description clearly states the tool loads a screening workflow for finding, filtering, scanning, ranking stocks, and gives specific examples like 'find stocks that...' and 'top 10 by...'. This differentiates it from sibling workflow tools that focus on backtesting, comparisons, etc.

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 specifies prerequisites: 'REQUIRES get_database_schema then get_query_patterns to be called first' and provides clear when-to-use guidance: 'Call BEFORE writing SQL when the user asks to find, screen, scan, rank, or filter stocks'. It also includes example queries and notes combinability with other workflow 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=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: the loading of a technical workflow and the prerequisite execution order, which is not captured by annotations alone.

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

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

Two concise sentences plus a clear prerequisite line. Every sentence adds value. Purpose is front-loaded, and 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?

Given the tool has zero parameters, an output schema (present), and comprehensive annotations, the description covers purpose, prerequisites, usage triggers, and combinability. It is complete for an AI agent to use correctly.

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

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

Input schema is empty with 100% coverage. No parameters to explain. This score is ideal for a zero-parameter tool.

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 loads a technical workflow for a comprehensive list of indicators (RSI, MACD, SMA, Bollinger Bands, entry/exit signals). It also specifies when to call it ('Call BEFORE writing SQL when the user asks about...') and distinguishes from siblings like load_backtesting_workflow and load_fundamental_workflow.

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 prerequisites: 'REQUIRES get_database_schema then get_query_patterns to be called first (in that order).' Provides specific usage contexts (when user asks about technical indicators) and notes it can be combined with other workflow tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds critical behavioral details: dependency on other tools, requirement for 'shibui.' table prefix and LIMIT clause, and user_prompt expansion rules. 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?

Description is concise (three paragraphs) and well-structured: starts with a summary of data types, then states main function, then prerequisites with order, then warnings. Every sentence adds value, no filler.

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

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

Given the tool's complexity (dependencies, specific query requirements), the description is complete. It explains the prerequisite sequence, query constraints, and user_prompt handling. The output schema exists but is not needed in description.

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

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

Schema description coverage is 100% and already explains both parameters well (query requires 'shibui.' prefix and LIMIT, user_prompt must be verbatim or expanded). The description adds no significant additional semantic value beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states the tool runs SQL queries against US stock market data, listing covered data types (prices, earnings, etc.). It distinguishes from sibling tools like load_*_workflow (which load predefined workflows) and get_database_schema/get_query_patterns (which are prerequisites).

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

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

Description explicitly requires calling get_database_schema then get_query_patterns first, warns of timeouts/wrong results without patterns, and explains the user_prompt parameter's role. This provides 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.