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

No annotations are provided, so the description carries the full burden. It only discloses the admin requirement but omits important behavioral traits such as possible side effects, rate limits, or what happens if users are already members.

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, consisting of two short sentences with no superfluous information. Every word 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 the simplicity of the tool and lack of annotations/output schema, the description is incomplete. It fails to mention return values, error handling, or behavior in edge cases (e.g., adding duplicate users).

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 both parameters (chat_id and user_ids) with 100% coverage. The description adds no new semantic meaning beyond restating 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 action (add one or more users) and the resource (group chat), using a specific verb and resource. It distinguishes itself from sibling tools like 'remove_member' by the action. However, it lacks explicit differentiation from other 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 a key prerequisite (bot must be admin of the chat) but does not offer guidance on when to use this tool versus alternatives, nor does it mention when not to use it.

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

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

Discloses key behaviors (update text, show notification, time limit) without annotations. Could mention callback acknowledgment but still good.

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 with no waste. Front-loaded with 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?

Covers main actions and constraint. No output schema, but description is sufficient for a callback response tool. Could mention error handling but not required.

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 3. Description adds minimal extra context beyond parameter descriptions (e.g., 'and/or' linking parameters).

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

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

Clearly states verb 'respond' and resource 'inline button click (callback event)'. Distinguishes from sibling editing tools by specifying it is for callbacks only.

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 timing constraint (30 seconds) and context for when to use. Lacks explicit when-not-to-use or alternatives, but the context is sufficient.

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?

No annotations are provided, so the description carries full burden. It does not mention whether deletion is permanent, if any permissions are needed, or what happens to the message after deletion. The term 'delete' implies destructiveness but lacks specifics.

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 short sentence, efficient and front-loaded. However, it could have included more concise details without becoming verbose.

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

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

Given no output schema and no annotations, the description should explain scope (only bot's messages) and provide context. It lacks completeness for a tool with only one parameter and simple 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 the description adds no extra meaning beyond what's in the schema. The description 'Requires the message_id' is redundant, not additive.

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

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

The description clearly states the action (delete) and the resource (a message sent by the bot), which is specific and distinct from sibling tools like edit_message or send_message.

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

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

No explicit guidance on when or when not to use this tool. It only reiterates the required parameter, missing context like that it only works for bot's own messages or that the message_id must come from a prior action.

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?

No annotations are provided, so the description carries full burden. It states the admin requirement but does not disclose potential side effects, whether changes are reversible, or error handling (e.g., what happens if not admin). Minimal behavioral context beyond the basic operation.

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-loading the key actions and then stating the admin requirement. Every word is necessary, 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?

No output schema exists. The description covers the purpose and a critical requirement, but fails to mention idempotency, notification behavior (though schema has notify_members), or error conditions. For a mutation tool with 5 parameters, it is somewhat incomplete.

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 description does not need to add parameter details. The description lists the actions (rename, change description, update icon) which maps to params title, description, icon, but adds no additional meaning or nuance 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's actions: rename a chat, change description, or update icon. It uses a specific verb ('edit') and resource ('chat'), and distinguishes from siblings like edit_message by focusing on chat-level properties.

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 a prerequisite (bot must be admin), which helps in usage. However, it does not provide guidance on when to use this tool vs alternatives like get_chat or delete_message, nor when not to use it.

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

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

No annotations present, so description must disclose behavior. It only states editing text and attachments, but omits details like whether edits are tracked, trigger notifications, or require specific permissions. Lacks depth for a mutation tool.

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, front-loaded with the core action and resource. No fluff, every word 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?

No output schema, and description does not explain return value, error handling, or success/failure indications. For a tool with 4 parameters and no annotations, more context is 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?

Schema covers all 4 parameters fully, so description adds minimal value. It clarifies attachments are 'inline keyboard buttons' and 'optional', but schema already conveys this. 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?

Clearly states the tool edits the text of an existing message sent by the bot, and optionally updates attachments. The verb 'edit' and resource 'message' are specific. It implicitly distinguishes from send_message and delete_message, but doesn't explicitly contrast.

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?

Mentions requirement of message_id and that it edits bot's own messages, providing some usage context. However, it does not give explicit guidance on when not to use or suggest alternative tools like send_message for new messages.

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?

No annotations are provided, so the description carries the full burden. It discloses the return fields (user_id, name, username, permissions) but does not mention whether the bot must be an admin or what happens for non-group chats.

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 front-load the purpose and output. No redundant information.

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

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

For a simple read tool with one parameter and no output schema, the description is fairly complete, specifying the returned fields. However, it lacks details on error cases or permission requirements.

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 parameter description in the schema is adequate. The description adds no extra meaning beyond identifying the chat type as a group chat.

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 'Get' and the resource 'list of administrators in a group chat'. It distinguishes from sibling tools like set_admin and remove_admin which modify rather than read.

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

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

No explicit when to use or when not to use this tool. While reading the admin list is implied, there is no mention of alternatives or prerequisites like requiring bot admin rights.

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?

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as read-only nature or lack of side effects. For a simple info retrieval tool, this is adequate but could be improved by explicitly stating that no modifications occur.

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 short sentences with no wasted words. The first sentence states the action, the second provides the use case. Front-loaded and efficient.

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

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

Given no parameters, no output schema, and no annotations, the description covers purpose and usage. It does not detail the output structure but lists some fields. This is reasonably complete for a simple 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 has zero parameters, so baseline is 4. The description adds value by listing the information returned (name, username, user_id, description), which is 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 'Get', the resource 'MAX bot info', and specifies the fields returned: name, username, user_id, description. It distinguishes itself from sibling tools that deal with chats, messages, and members.

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: 'Use this to verify the bot is connected and working.' It does not list alternatives but the purpose is clear enough for an agent to choose this over 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?

No annotations exist, so description must bear full burden. It states what is retrieved but does not disclose potential limitations, error handling, authentication needs, or that it is a read-only operation. Minimal 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?

Single concise sentence that front-loads the purpose and lists outputs. No 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?

For a simple retrieval tool with one required param and no output schema, the description is largely complete. Missing return type but acceptable given simplicity.

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% (one parameter chat_id with description). The description adds value by listing the returned fields but does not enhance the parameter's meaning beyond the schema. 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?

Description clearly states the verb 'get' and resource 'full details of a specific chat by its ID' and lists the fields returned, distinguishing it from sibling tools like get_chats (listing) and edit/delete 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?

No guidance on when to use this tool versus alternatives, no exclusions or when-not-to-use instructions. Sibling tools include many similar operations but no distinction is 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?

No annotations provided, so description carries full burden. It returns participant fields but does not disclose read-only nature, pagination behavior, or any prerequisites. Schema covers some aspects, but description lacks 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?

Single sentence, front-loaded with action, no filler. Efficient and clear.

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 no output schema, the description provides return fields. It mentions group chat scope. Could explain pagination more, but schema covers marker and count. Overall adequate.

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 all params. The description adds no extra detail about parameters beyond the schema, but summarizes return fields. 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 'Get the list of participants in a group chat' with a specific verb and resource. It distinguishes from sibling tools like get_admins or get_chat by focusing on members.

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

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

No explicit guidance on when to use or avoid this tool. The description implies it's for listing members, but does not mention alternatives or conditions like required permissions.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It notes that only group chats are returned and that chat_id can be used for subsequent actions. However, it does not mention pagination behavior beyond the marker parameter description in the schema, which is a minor gap.

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, each serving a distinct purpose: stating the core function, listing returned fields, and providing usage guidance with alternatives. 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's simplicity (two optional parameters, no output schema), the description is complete. It covers purpose, return values, usage context, and limitations. Additional details like pagination are implied by the marker parameter 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?

The input schema covers 100% of parameters with descriptions. The tool description adds value by explaining how to use the results (e.g., chat_id for reading/sending messages), which goes beyond the schema's parameter 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 that the tool retrieves all group chats where the bot participates, listing specific returned fields (chat_id, title, type, etc.). It effectively distinguishes itself from sibling tools like get_updates by clarifying that personal dialogs are excluded.

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 (to get group chats) and when not to (for personal dialogs), providing the alternative get_updates. This gives clear guidance for 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?

No annotations are provided, so the description carries the full burden. It states the tool returns full message details, which is adequate for a simple read operation. However, it does not disclose potential authorization needs or failure modes.

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, no wasted words. The description is front-loaded with the essential purpose and returns, earning 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 the tool's simplicity (one parameter, no output schema), the description covers purpose and return details adequately. Could optionally mention error conditions, but overall complete enough.

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% as the single parameter 'message_id' is described. The description adds no extra meaning beyond the schema's 'Message ID (mid) to retrieve', 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?

The description clearly states the verb 'Get', the resource 'a single message', and the method 'by its ID'. It distinguishes from sibling 'get_messages' by specifying 'single', and mentions return details including text, sender, attachments.

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

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

The description implies use for retrieving a single message by ID, contrasting with 'get_messages' for multiple. However, no explicit when-not or alternative guidance is provided beyond the implicit differentiation.

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

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

With no annotations, the description covers key behaviors: read operation, mutual exclusivity, and conditional parameter usage. It does not mention error handling or default behavior when no parameters are provided.

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, no fluff. Purpose is front-loaded, followed by concise usage instructions for both modes.

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?

Description provides enough to use the tool correctly given the schema and context, but lacks mention of return format (e.g., array of message objects), which would improve completeness.

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 descriptions cover all parameters (100% coverage). The description adds value by explaining the mutual exclusivity and that count/from/to are only used with chat_id, which is not fully clear from the 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 states the tool reads messages from a MAX chat and distinguishes two modes (by chat_id or message_ids), differentiating it from siblings like get_message or send_message.

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 mutual exclusivity of chat_id and message_ids, and explains filtering with count/from/to when using chat_id. Lacks explicit comparison to sibling tools for when to use 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?

With no annotations provided, the description fully discloses behavioral traits: polling mechanism (marker for incremental updates, timeout for instant/long polling), event types list, and a crucial warning that this is for development only and not for production. 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 reasonably concise and front-loaded with the core purpose. It includes necessary detail without unnecessary verbosity, though the event types list could be more compact by referencing the schema.

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 4 parameters (all optional with enums/constraints), the description fully covers what the tool returns (events with types) and how to use it effectively (marker, timeout, production warning). 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%, so baseline is 3. Description adds some context (e.g., timeout=0 vs >0 behavior, marker pagination) but largely repeats schema descriptions. The event types list in description is slightly incomplete (missing 'chat_title_changed'), so not fully additive.

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

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

Description clearly states the tool gets incoming events (new messages, button clicks, etc.) and explicitly distinguishes itself as the only way to get chat_id for personal dialogs. The verb 'get' and resource 'updates' are clear, and it differentiates from sibling tools (e.g., send_message, get_message) by specifying polling behavior.

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 (for polling) and when not to (production should use webhooks). It provides detailed guidance on marker usage for pagination and timeout behavior (instant vs long polling), giving clear context for 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?

With no annotations, the description carries the full burden. It discloses the admin requirement but does not mention potential side effects (e.g., unpinning previous pinned message) or error conditions. The behavior is minimally described.

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 efficient sentences with no redundancy. The critical requirement (admin rights) is front-loaded, making the description immediately actionable.

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 should mention what the tool returns or any implicit behavior. It only states the action and prerequisite, omitting return type or success/failure indicators. This is insufficient for a complete understanding.

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 documentation covers all three parameters with descriptions (100% coverage). The description adds no extra meaning beyond the schema, so 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?

Description clearly states the verb 'pin' and resource 'message in a group chat'. It distinguishes from sibling tool 'unpin_message' and other editing tools.

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

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

Explicitly states the prerequisite (bot must have admin rights) and provides context for when to use. Does not mention when not to use or alternatives like unpin, but the prerequisite adds significant 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?

No annotations provided, so description carries full burden. It discloses the effect (member remains regular) and a critical known bug where success:true may be misleading. This adds significant behavioral context beyond the basic action.

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, then result, then important caveat. No filler 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?

Covers core behavior, required bot perms, and critical bug. Lacks output format or verification steps, but given simple 2-param tool with no output schema, it is fairly complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new information beyond what the schema already provides for each parameter. It mentions bot requirement, but that is not parameter-specific.

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 'Revoke admin rights from a chat member' with specific verb and resource. It distinguishes from siblings like set_admin and remove_member, which are listed in 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 requirement: 'The bot must be an admin or owner of the chat.' It also warns about a known API bug, guiding usage expectations. However, it does not explicitly state when not to use or name 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?

With no annotations, the description carries full burden. It discloses admin requirement, optional block, and a privacy mode warning that affects re-add capability. It omits success/error responses but covers key behavioral traits.

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 distinct purpose: core action, prerequisite, warning. Front-loaded and concise with 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?

The description covers core action, prerequisite, and a critical warning. Lacks return value information and error conditions, but is adequate for a removal tool given no output schema.

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 parameters. The description adds minimal extra meaning (e.g., 'optionally block' for the block parameter) but does not deepen 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 specific action: 'Remove a user from a group chat.' It identifies the resource (user) and context (group chat), and distinguishes from siblings like add_members and remove_admin.

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 a prerequisite (bot must be admin) and a warning, but does not explicitly compare to alternatives like remove_admin. It indirectly suggests when to use but lacks explicit 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?

No annotations are provided, so the description should disclose behavioral traits. It states the tool shows status indicators, implying a non-destructive read-like operation. However, it does not mention any side effects, duration of the indicator, or permissions required. This is adequate but minimal.

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 well-structured, with two sentences that front-load the purpose and usage. The list of actions is included but doesn't add fluff. 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 the simple tool with 2 parameters and no output schema, the description is complete enough. It covers what the tool does, when to use it, and the available actions. It lacks details on the duration of the status indicator, but that is 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?

The input schema covers 100% of parameters with descriptions. The description lists the actions (e.g., 'typing_on'), repeating the enum values, but does not add new semantic information beyond the schema. Baseline score of 3 for high schema coverage.

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: showing a typing indicator or other status to chat members. It specifies the verb 'show' and the resource 'typing indicator or other status', and lists the available actions, distinguishing it from sibling tools like send_message.

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 context: 'Use before sending a message to improve UX.' This guides the agent on when to invoke the tool. It could be improved by explicitly stating when not to use it (e.g., for sending actual messages), but the context is sufficient.

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 the automatic two-step upload process, a key behavioral trait. No annotations exist, so description effectively fills that gap.

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 highly informative sentences, no fluff, front-loaded with purpose, followed by process and ID requirement.

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

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

Covers main purpose, process, and ID constraint. Lacks error handling or rate limits, but overall sufficient for a media upload tool with no output schema.

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%, baseline 3. Description adds value by explaining mutual exclusivity of IDs and the automated process, surpassing schema details.

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 uploads a file from a URL and sends it as a message, distinguishing it from siblings like send_message for plain text.

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 'Provide either chat_id or user_id,' which guides selection. Lacks explicit when-not-to-use but context from siblings 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?

With no annotations provided, the description carries full burden. It mentions support for markdown and HTML formatting and hints at prerequisites (tokens from send_media for attachments). However, it does not disclose potential side effects, required permissions, rate limits, or the immediate behavior of message sending. Some behavioral traits like notification defaults are not addressed.

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 long and front-loaded with the primary purpose. Every sentence provides essential information without fluff. It is well-structured and easy to read.

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 (7 parameters, nested attachment types) and no output schema, the description is fairly complete. It covers the main use cases, provides necessary context for target selection, and flags requirements. However, it could benefit from mentioning return values or error handling, but overall it is adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying mutual exclusivity of chat_id/user_id and recommending use of send_media tokens. However, it does not provide additional syntax or examples for the complex attachments parameter beyond what the schema already details.

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: 'Send a text message to a MAX chat or user.' It distinguishes between group chats and direct messages by specifying the use of chat_id or user_id. This is specific and differentiates from siblings like send_media.

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 guidance on how to use the tool: 'Provide either chat_id (group chats/channels) or user_id (direct messages), not both.' It also mentions using attachments from send_media. However, it does not explicitly state when not to use this tool or compare with alternatives like send_media or send_action.

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

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

With no annotations, the description must fully disclose behavior. It mentions a key constraint (bot must be admin/owner) but omits other important behaviors: what happens if the user is already an admin, if the chat is not a group, or if the bot lacks permissions. The description is incomplete for a mutation tool.

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

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

Two sentences with no fluff. The description is front-loaded with the primary action, then adds the prerequisite. 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 tool (2 required params, no output schema, no annotations), the description covers the core function and a key prerequisite. However, it lacks details on error conditions, idempotency, and what constitutes a valid chat, making it adequate but not fully complete.

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

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

Schema coverage is 100% (both parameters have descriptions). The description adds no additional meaning beyond the schema, such as value formats or validation rules. Baseline 3 is appropriate given high coverage.

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 action ('Grant admin rights') and the target resource ('a chat member'). This distinguishes it from siblings like 'remove_admin' or 'get_admins', 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 includes a crucial prerequisite ('The bot must be an admin or owner'), but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when to use 'remove_admin' instead) or when not to use it. The context is implied but not fully fleshed out.

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?

No annotations are provided, so the description carries the full burden. It explains the basic action and a prerequisite but does not disclose behaviors like what happens if no message is pinned or error handling.

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

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

Extremely concise: two sentences, front-loaded with the main action and a critical condition. No unnecessary information.

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

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

The description is adequate for a simple tool with one parameter and no output schema. It covers the essential purpose and a key prerequisite. Minor gaps like missing error cases do not significantly hinder use.

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

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

Schema coverage is 100% with a clear description for 'chat_id'. The tool description does not add additional meaning beyond the schema.

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

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

The description clearly states the action ('Unpin') and the resource ('currently pinned message in a group chat'). It is specific and distinguishable from the sibling tool 'pin_message'.

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 a key prerequisite ('bot must have admin rights'), which guides when the tool can be used. It does not explicitly state when not to use it, but the sibling context makes alternatives clear.

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