Server Quality Checklist

Tool Scores

• get_participantsC
  2.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries full burden; it discloses 'read-only' which is a helpful safety trait, but does not mention behavior such as pagination, ordering, or error conditions. This is minimal but non-contradictory coverage.

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

  Conciseness3/5

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

  The description is very short and front-loaded, but it includes an opaque internal reference (T12: iter_participants) that adds noise for an AI agent. It is concise but not effectively structured for external consumers.

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

  Completeness2/5

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

  For a simple read-only participants tool, the description covers the basic safety profile, but with no annotation support and no parameter explanations, it leaves the agent uncertain about required inputs and output specifics. The presence of an output schema mitigates return-value explanation, but the context is still thin.

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

  Parameters2/5

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

  The schema has 0% description coverage, and the description does not explain the 'chat' or 'limit' parameters. The internal 'iter_participants(entity, limit)' reference is ambiguous and does not map cleanly to the schema, so it fails to compensate for the missing schema descriptions.

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

  Purpose4/5

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

  The description clearly identifies the resource as chat/group participants and its read-only nature, but lacks an explicit verb. The name 'get_participants' reinforces the purpose, and it is distinct from sibling tools focused on history, pinned messages, or chats.

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

  Usage Guidelines2/5

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

  The description offers no guidance on when to use this tool versus alternatives like get_history or list_chats. It only mentions read-only and an internal iteration label, which does not help select among siblings.

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

• list_chatsB
  3/5.0
  Behavior3/5

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

  The description includes 'read-only', a key behavioral trait, and mentions an internal mapping to chat_brief. However, it does not clarify how 'unread' filters work or whether any authorization is required, leaving some behavioral aspects ambiguous.

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

  Conciseness4/5

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

  The description is brief and front-loaded with the purpose, but the 'T5' technical note is cryptic and adds noise without clear benefit.

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

  Completeness3/5

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

  For a simple list tool with an output schema, the description covers return fields and read-only nature, but misses parameter semantics and usage alternatives, leaving the tool under-specified for correct invocation.

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

  Parameters2/5

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

  The description only repeats parameter names in a function signature ('iter_dialogs(limit, archived)') without explaining their meaning or effect. The input schema provides types and defaults, but no descriptions, so the description adds no value.

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

  Purpose4/5

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

  The description states the tool lists dialogs with unread messages, including title, type, unread_count, and last message. The verb 'Список' (list) and resource 'диалогов' (dialogs) make the core purpose clear, though it does not explicitly distinguish from sibling tools like digest_unread.

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

  Usage Guidelines2/5

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

  No guidance is provided about when to use this tool versus alternatives. The description lacks context about filtering behaviors or comparison to other list/read tools.

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

• get_pinnedB
  3.1/5.0
  Behavior3/5

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

  The description explicitly states 'read-only', which is a useful safety trait given no annotations are provided. However, it does not disclose authorization requirements, rate limits, pagination, or error behavior, and the 'T12/iter_messages' reference adds little behavioral clarity.

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

  Conciseness4/5

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

  The description is very concise and front-loaded with the core purpose. However, the 'T12: get_pinned / iter_messages(pinned)' segment is cryptic and arguably unnecessary for an agent, reducing clarity slightly.

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

  Completeness3/5

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

  This is a simple one-parameter read-only tool with an output schema, so return values need not be described. Still, the absence of any usage guidance or parameter format details leaves some gaps, though the core purpose is clear.

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

  Parameters1/5

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

  The only parameter 'chat' is a required string with schema description coverage of 0%. The description mentions 'чата' (of chat), but this merely restates the parameter name and does not specify format (ID vs username), validation rules, or how it should be obtained.

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

  Purpose5/5

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

  The description clearly states the tool retrieves pinned messages of a chat, a specific resource that distinguishes it from siblings like get_history or list_chats. The verb 'get' is implied by the name and reinforced by the phrase 'pinned messages of chat'.

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

  Usage Guidelines2/5

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

  No guidance is provided on when to use this tool versus alternatives, such as get_history or search_in_chat. The 'T12: get_pinned / iter_messages(pinned)' reference is an implementation hint, not usage guidance.

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

• search_in_chatA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses 'read-only' behavior and references the underlying iter_messages method, indicating it calls a Telegram API. However, it does not mention pagination, ordering, search case-sensitivity, or what happens with no results. The added context is helpful but incomplete.

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

  Conciseness5/5

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

  The description is extremely concise, with two sentences that front-load the purpose and provide a technical shortcut. No redundant content or filler; every phrase contributes to understanding the tool's function and underlying call.

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

  Completeness4/5

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

  For a simple search tool with an output schema, the description is largely sufficient. It captures the core behavior, read-only nature, and parameter mapping. However, it doesn't explain how to specify the 'chat' parameter (e.g., ID vs username) or the query syntax, which could cause misuse. Given the tool's low complexity, it is nearly complete.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. The T7 line maps query and limit to iter_messages parameters, giving meaning to those. However, the 'chat' parameter is not explained (e.g., what format or how to obtain it), and query is not described beyond 'по тексту'. The description adds partial value but leaves gaps.

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

  Purpose5/5

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

  The description clearly states the tool searches for messages inside a chat by text ('Поиск сообщений ВНУТРИ чата по тексту'), using a specific verb and resource. It distinguishes from sibling tools like get_history by focusing on text search within a specific chat. The additional T7 mapping reinforces the purpose.

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

  Usage Guidelines3/5

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

  The description implies usage scope with 'ВНУТРИ чата', but does not explicitly state when to use this tool versus get_history or digest_unread. No alternative tools are named, and no exclusions are provided. The T7 hint gives a usage pattern but not decision guidance.

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

• download_mediaA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses that the operation is read-only ('read-only (download_*)') and writes locally ('на диск (локально)'), which is valuable. But it omits potential side effects like file overwriting, permission requirements, or error behavior, making it only partially transparent.

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

  Conciseness4/5

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

  The description is concise, with three sentences that each add value: the main action, a usage pattern, and scope/read-only notes. The code snippet is useful but adds minor overhead; overall it is well-structured and front-loaded.

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

  Completeness4/5

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

  The output schema is present, so return values are covered elsewhere. The description provides a usage pattern and a clear scope, but does not address edge cases like messages without media or file-naming behavior. Still, for a straightforward download tool, it is fairly complete.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. The code snippet provides context for message_id and dest but does not explicitly explain the 'chat' parameter. It gives the relationship between parameters but lacks detailed semantics for types or constraints, so the compensation is partial.

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

  Purpose5/5

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

  The description clearly states the tool downloads a specific message's attachment to disk locally, using the verb 'Скачать' (download) and the resource 'вложение из конкретного сообщения' (attachment from a specific message). It explicitly distinguishes itself from bulk operations with 'Точечно, не «все фото»' (Specifically, not all photos), and the code snippet reinforces the exact action.

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

  Usage Guidelines4/5

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

  The description provides clear usage context with the workflow 'get_messages(entity, ids=message_id) → message.download_media(dest)' and an explicit exclusion 'не «все фото»' (not all photos). However, it does not name an alternative tool for bulk downloads, so it falls short of a 5.

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

• get_meA
  3.9/5.0
  Behavior4/5

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

  The description explicitly states 'read-only', providing crucial behavioral disclosure in the absence of annotations. It also lists the output fields, adding useful context about what the tool returns and confirming no 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.

  Conciseness5/5

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

  The description is a single concise line that conveys purpose, read-only behavior, and output fields without any redundant or irrelevant information. Every word earns its place.

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

  Completeness4/5

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

  For a parameterless tool with an output schema, the description is sufficiently complete. It covers the essential points: what the tool does, its read-only nature, and what data it returns. It could mention authentication requirements, but for a simple self-info tool this is adequate.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema is empty. The description adds value by specifying the return fields (id, name, username), giving the agent a clear expectation of the tool's output despite having no inputs to document.

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

  Purpose4/5

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

  The description clearly identifies the resource as the current account and lists return fields (id, name, username). It distinguishes from sibling tools by focusing on the user's own account rather than chats or media, though it lacks an explicit verb like 'retrieves'.

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

  Usage Guidelines3/5

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

  No explicit guidance on when to use this tool versus alternatives, but the purpose is implied by the name and description. It implicitly indicates use for getting current account information without stating exclusions or alternative tools.

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

• digest_unreadA
  4/5.0
  Behavior5/5

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

  The description explicitly discloses key behavioral traits: it does NOT mark messages as read ('Чтение НЕ помечает прочитанным'), is read-only, sorts by unread_count descending, returns newest-first, and includes a FloodWait limitation. Since no annotations are provided, the description fully carries the transparency burden and does so thoroughly.

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

  Conciseness3/5

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

  The description is moderately concise but contains fluff like 'KILLER-тул' and 'T9:', which add no functional value. It also repeats the 'not marked as read' point twice, making it slightly less tight. The core algorithm is clearly front-loaded, but the redundancy and informal jargon reduce efficiency.

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

  Completeness4/5

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

  The description covers essential context: algorithm, sorting, read-only behavior, and rate-limit awareness. An output schema exists, so return values need not be described. It lacks edge cases (e.g., behavior when no unread chats exist), but overall it is sufficiently complete for a read-only digest tool.

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

  Parameters3/5

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

  The input schema already provides 100% coverage with clear descriptions for 'top' and 'per_chat', so the description does not add significant semantic value. It merely references these parameters in the algorithm without new details, aligning with the baseline for full schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool's purpose as a digest of unread messages ('дайджест непрочитанного') and outlines the algorithm (iter_dialogs → top chats with unread_count > 0 → fetch recent messages). It distinguishes itself from sibling tools like get_history or list_chats by focusing on unread counts and read-only aggregation.

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

  Usage Guidelines3/5

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

  The description implies the tool is for catching up on unread messages and mentions read-only behavior, but it does not explicitly state when to use it over alternatives or provide exclusions. No named sibling alternatives are given, so usage context is only implied.

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

• get_historyA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It explicitly states the tool is read-only and discloses the return structure via the T6 notation ({id, date, sender, text}). This is useful context beyond the schema, though it omits error scenarios or authentication requirements.

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

  Conciseness5/5

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

  The description is succinct with two sentences, front-loading the core purpose first. Every phrase adds value: chat resolution format, the underlying method call, and the return shape. No unnecessary filler.

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

  Completeness4/5

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

  Given the output schema exists and the tool is simple and read-only, the description is largely complete. It covers purpose, parameter flexibility, and return values. However, it lacks usage guidance and error conditions, which slightly detracts from full completeness.

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

  Parameters4/5

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

  Schema coverage is 0%, so the description must compensate. It explains the 'chat' parameter can be an id, username, link, or name, and that it resolves to an entity. 'limit' is mentioned in the T6 call, implying it controls the number of messages, though not explicitly defined.

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

  Purpose5/5

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

  The description clearly states the tool retrieves recent chat messages, with a specific resource (chat) and verb implied by the name. It distinguishes itself from siblings like search_in_chat and get_pinned by focusing on message history. The resolution detail for chat adds specificity.

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

  Usage Guidelines2/5

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

  No explicit guidance is given on when to use this tool versus alternatives. The description explains what the tool does but not the appropriate context or exclusions, leaving the agent to infer usage from the name and sibling list.

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

• find_chatA
  4.1/5.0
  Behavior5/5

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

  No annotations are provided, so the description fully carries the behavioral disclosure burden. It reveals the response structure (ranked matches in my_results and results), the selection logic (taking only my_results→results, not the entire pool), and explicitly declares the operation as 'read-only'. This goes well beyond a simple statement of what the tool does.

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

  Conciseness4/5

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

  The description is longer than a minimal one-liner, but each sentence adds valuable context about ranking, selection, and fallback. It is front-loaded with the core purpose and then flows into implementation details. The TODO note is slightly tangential but relevant to future behavior, making the description efficient overall.

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

  Completeness4/5

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

  The tool is moderately complex (server-side search with ranking, multiple result sets, and a fallback path). The description covers the behavioral flow, selection criteria, and read-only nature. It omits details like error handling or rate limits, but the presence of an output schema makes the absence of explicit return-value description acceptable. The description is complete enough for an agent to invoke the tool correctly.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. The query parameter is implied as the search string, but the limit parameter is not described at all. No additional meaning is added beyond the field names, failing to fully compensate for the schema's lack of descriptions.

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

  Purpose5/5

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

  The description clearly states 'Find chat by search (not by iterating over dialogs)' and specifies 'server-side contacts.Search', identifying the exact verb, resource, and method. It also distinguishes from sibling tools by explicitly contrasting with iterating over dialogs (list_chats) and implying a search scope different from search_in_chat.

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

  Usage Guidelines4/5

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

  It provides clear context for when to use this tool: for search-based lookup of chats/contacts rather than brute-force iteration over dialogs. It mentions a fallback to local filtering as a TODO, implying the current server-side search is the primary approach. However, it doesn't explicitly name alternative tools or provide detailed when-not-to-use scenarios beyond the 'not iterating dialogs' exclusion.

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

• resolve_chatA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description discloses that the operation is read-only and that missing entities cause a Telethon exception (ValueError/UsernameNotOccupiedError) to be propagated to the owner. This is useful context beyond the schema, though it could mention authorization or network behavior.

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

  Conciseness5/5

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

  The description is three short lines: the main purpose, a compact signature, and an error-handling note. No filler; information is front-loaded.

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

  Completeness5/5

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

  With a single parameter and an output schema present, the description sufficiently covers what the tool does, accepted input formats, and what happens on failure. It does not need to list return fields since the output schema exists.

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

  Parameters5/5

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

  The schema only defines ref as a string, but the description defines accepted forms: username, link, id, or exact name. This gives the agent necessary meaning for the parameter.

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

  Purpose5/5

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

  The description opens with 'Точный resolve чата/юзера' specifying exact resolution of chat/user and enumerates accepted reference types (username/link/id/exact name). This makes the tool's purpose specific and distinguishes it from sibling search tools like find_chat.

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

  Usage Guidelines3/5

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

  The description implies this is for exact lookup by reference but does not state when to prefer it over find_chat or other siblings, nor does it mention exclusions. The 'read-only' note helps but doesn't provide explicit usage guidance.

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