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

No annotations are provided, so the description carries full behavioral disclosure. It states the action but does not describe what happens when called, such as whether an SMS is actually sent, rate limits, code expiration, or behavior if the phone number is already registered.

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, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose and scope.

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 an output schema present, return values need not be explained. However, the description leaves the sole parameter undocumented and provides no behavioral context despite missing annotations, making it minimally adequate for a simple auth-initiation tool.

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

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

Schema description coverage is 0%, and the single parameter 'phone_number' has no description in the schema. The description only implies it via 'phone login' and does not specify format, country code, or other details needed to invoke correctly.

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 states a specific verb (requesting) and resource (SMS/Bale verification code) for interactive phone login, and adds the scope 'for a new account' to distinguish it from password-based login. It does not explicitly name a sibling tool, but the action and context are clear.

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

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

The description gives clear context: use this to initiate phone login for a new account. It implies this is the first step in the auth flow, though it does not name alternatives or prerequisites (e.g., that bale_auth_verify_code should follow).

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 carry the full behavioral burden. It discloses that a session is saved after verification, which is useful, but does not mention error handling, code expiration, rate limits, or what happens on failure. The output schema exists, so return value details are not needed, but other behavioral traits remain undisclosed.

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

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

The description is a single, well-structured sentence that front-loads the core action and includes the key outcome. 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?

Given no annotations, 0% schema description coverage, and a required parameter plus an optional parameter, the description is incomplete. It omits crucial context about the 'transaction_hash' parameter and behavioral details like error conditions, which are necessary for correct invocation.

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

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

Schema description coverage is 0%, and the description provides no details about the parameters. The 'code' parameter is somewhat implied, but 'transaction_hash' is not mentioned at all, leaving its purpose and usage completely undocumented.

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

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

States a specific verb (Verify) and resource (authentication code received via SMS/Bale), and clarifies the outcome (complete login and save session). It is distinguishable from siblings like bale_auth_request_code and bale_auth_verify_password, though it doesn't explicitly name alternatives.

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

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

The description implies usage after receiving a code, but does not explicitly state when to use this tool over bale_auth_verify_password or other alternatives. The context is clear but lacks exclusions or explicit comparisons.

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 conveys that this is a conditional login step, but says nothing about failure behavior, retry/rate limits, what state the session must be in, or the role of the transaction_hash — significant gaps for an authentication mutation.

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?

A single front-loaded sentence with no filler — the core action and its condition are stated immediately. It is efficient, though it is arguably too terse given the undocumented parameter.

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?

An output schema exists, so return values need not be explained. Still, for an auth tool in a multi-step login flow with an unexplained transaction_hash and no annotations, the description leaves real gaps about sequencing and preconditions.

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 0%, so the description must compensate. It implicitly explains 'password' as the cloud password, but the second parameter, transaction_hash, is completely undocumented in both the schema and the description, leaving an agent unable to know what it is or when to supply it.

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 gives a specific verb and resource ('Submit Two-Factor Authentication (2FA) cloud password') and scopes it to login, which clearly separates it from the sibling bale_auth_verify_code. It does not, however, explicitly name that sibling or contrast the two, so it falls short of a 5.

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?

'if required during login' implies the triggering condition, but there is no explicit when-to-use/when-not or reference to alternative siblings like bale_auth_verify_code. An agent can infer the auth-flow position but must guess the relationship between the two verify 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?

With no annotations provided, the description carries the full behavioral burden. It does not say what blocking entails (e.g., suppressing inbound messages), whether the action is reversible, whether it requires connection/authentication, or any rate limits — all relevant 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?

A single short, front-loaded sentence with zero filler. It is efficient, though arguably too terse to be self-sufficient for a mutation 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?

An output schema exists, so return values need not be explained. However, with no annotations and no guidance on authentication or reversibility, the definition is only minimally complete for an action that alters user relationships.

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 0%, so the description must compensate. "By user ID" does identify that the single parameter is a user identifier, adding marginal meaning, but gives no format or sourcing hints (e.g., from bale_search_user) beyond the schema's integer type.

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

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

States a specific verb ("Block") and resource ("a user") with the identifier scope, so the action is immediately clear. It does not differentiate from the sibling bale_unblock_user or clarify blocking semantics, but the core purpose is 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?

There is no when-to-use guidance, no mention of the reciprocal tool bale_unblock_user or the read-only bale_get_blocked_users sibling, and no prerequisites such as needing an authenticated session. The agent must infer everything about 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?

With no annotations provided, the description carries the full behavioral burden, and it does not say what happens to an already-active session on switch, whether this requires prior authentication, or whether any state is mutated or destroyed. Output schema exists so return values need less coverage, but the side-effect profile of a 'switch' operation is undisclosed.

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?

A single front-loaded sentence with no padding; the core action and target are stated immediately. It is efficient, though the phone-number clause adds a small ambiguity rather than 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?

For a one-parameter tool with an output schema, the description is roughly adequate but omits key operational context: whether a prior session is replaced, auth prerequisites, and how the session identifier maps to the parameter. The 'phone number' mention also introduces an unresolved gap versus the 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 description coverage is 0% and the sole parameter is undocumented in the schema, so the description must compensate. It adds partial meaning by indicating the value may be a session name or phone number, but does not resolve the mismatch with the schema's 'Session Name' title or explain expected formats.

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

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

States a specific verb ('connect to or switch to') and resource ('a specific Bale user account'), which cleanly separates it from siblings like bale_list_sessions and bale_auth_request_code. However, it claims 'session name or phone number' while the schema exposes only a single 'session_name' string, so the stated input surface is slightly inconsistent with the actual 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?

There is no explicit guidance on when to use this versus bale_list_sessions or the auth tools, nor any stated prerequisite (e.g., whether a session must already exist or whether auth is required first). 'Connect to or switch to' hints at the usage context but leaves the agent to infer 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 are provided, so the description carries the full behavioral burden, yet it only says a group/channel is created with initial members. It omits auth/permission requirements, whether the operation is idempotent or reversible, rate limits, and what happens on duplicate usernames or invalid user_ids.

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?

A single front-loaded sentence with no filler. It is efficient, though arguably too terse given how much semantic ground the tool must cover.

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?

An output schema exists so return values need not be described, but for a 4-parameter mutating tool with no annotations and 0% schema coverage the description is far too thin. It leaves required-parameter semantics and behavioral consequences undocumented.

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 0%, so the description must compensate for all four parameters. It only implicitly maps 'channel' to is_channel and 'initial members' to user_ids, leaving the required 'title' and the 'username' parameter completely unexplained in both schema and description.

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

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

Clear verb ('Create') plus resource ('group or channel') and platform ('on Bale'), which is enough to distinguish it from siblings like bale_invite_to_group, bale_leave_group, and bale_get_group_info. It does not explicitly name an alternative sibling, so it falls just short of the top tier.

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

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

The description gives no when-to-use guidance, prerequisites, or exclusions. An agent must infer usage entirely from the name, and it is not told how this differs from invitatory tools like bale_invite_to_group when adding members.

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, yet it only states the mutation. It does not say whether deletion is permanent or reversible, whether it requires being the sender or an admin, or what 'just_me' implies about scope.

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?

A single efficient sentence with no padding, and the verb is front-loaded. It is under-specified rather than verbose, so conciseness itself is not the failing.

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?

An output schema exists, so return values need not be explained, but for a destructive mutation with no annotations and 0% parameter coverage the description is far too thin. Permission requirements, reversibility, and the just_me/chat_type semantics are all missing.

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

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

Schema description coverage is 0% for all 4 parameters, and the description only loosely implies chat_id and message_id ('from a chat'). It says nothing about the meaning or effect of just_me or chat_type, leaving half the parameters undocumented.

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

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

States a specific verb and resource ('Delete a message') and implies the chat context, so the action is unambiguous. It does not differentiate itself from siblings like bale_edit_message or bale_forward_message, which is the only thing keeping it from a 5.

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 versus bale_edit_message or other message-mutating siblings, and no prerequisites such as required permissions. The agent must infer everything from the tool name alone.

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 behavioral burden. It says it targets the 'currently active' account, but does not disclose whether the session token is invalidated, whether re-authentication is required afterward, or whether the action is reversible.

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?

A single front-loaded sentence with no filler; 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?

An output schema exists, so return values need not be explained, and the no-parameter surface keeps things simple. However, for a session-terminating mutation with no annotations, the description omits auth requirements and post-disconnect state, leaving meaningful 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?

The tool takes zero parameters, so there is nothing to document; baseline 4 applies. The description correctly implies no input is needed to act on the active account.

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

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

States a specific verb ('Disconnect') and resource ('the currently active Bale user account'), which is clearly distinct from siblings like bale_connect_session and bale_list_sessions. It does not explicitly name or contrast a sibling, but the operation is 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?

No guidance on when to use this versus alternatives such as bale_list_sessions or bale_connect_session, and no prerequisites stated. The agent must infer that this tears down the active session.

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. 'Sent previously' and 'text message' imply the target must exist and be of text type, which is some value, but it omits whether the caller must own the message, permission/auth requirements, reversibility, and error behavior for non-text or non-editable messages.

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?

A single front-loaded sentence with no redundancy; the operation and its target are stated immediately. It is arguably under-specified rather than wasteful, but structurally clean.

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?

A mutation tool with no annotations, 0% schema coverage on four parameters, and only a one-line description leaves significant gaps. The output schema covers return values, but the missing permission model, constraints, and parameter meaning make this incomplete for correct invocation.

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

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

Schema description coverage is 0% across four parameters, so the description must compensate but does not. It never mentions chat_id, message_id, new_text, or the chat_type default, leaving their format and meaning undocumented. Only a weak implied link ('text' to new_text) exists.

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

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

States a specific verb ('Edit') and resource ('existing text message') with a scope qualifier ('sent previously in a chat'). It is distinguishable from siblings like bale_send_message, bale_delete_message, and bale_forward_message, though it never explicitly names them. The 'text message' qualifier usefully hints at a type restriction.

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

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

The description gives no when-to-use or when-not-to-use guidance and does not point to any alternative such as bale_send_message for new messages. No prerequisites (e.g., must be the sender, must be within an edit window) are stated.

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 behavioral burden. It says nothing about permission requirements, whether the forwarded message retains sender attribution, rate limits, or what happens on invalid message_id — all significant for a mutation tool with zero annotation coverage.

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?

One tight, front-loaded sentence with no filler. It is efficient, though its brevity comes at the cost of the behavioral and parameter detail the tool needs.

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?

An output schema exists, so return values needn't be explained, but with no annotations, 0% schema coverage, and four required parameters, the description is far too thin for a mutation tool. It omits permission, attribution, and parameter-shape context an agent would need to invoke it correctly.

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

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

Schema description coverage is 0% across five parameters, and the description only loosely maps 'existing message' to message_id and 'another chat or user' to to_chat_id. It explains nothing about the from/to chat_id vs chat_type distinction that the schema leaves undocumented.

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

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

States a specific verb (forward) and resource (existing message) with a scope (another chat or user). It implicitly distinguishes itself from bale_send_message by emphasizing forwarding an 'existing' message, though it never names that sibling explicitly.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g. the message must already exist and be visible to the caller), and no routing between this and sibling messaging tools like bale_send_message or bale_edit_message. Usage is only vaguely implied.

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

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

No annotations are supplied, so the description carries the full behavioral burden. 'List' implies a non-destructive read, which is the key trait, but the description says nothing about authentication/session requirements, pagination, or whether the result is scoped to the active account only (it does imply the active account). Adequate but thin for a zero-annotation 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?

A single front-loaded sentence with no filler, and the scope ('currently blocked', 'active account') is packed into the first clause. Nothing 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?

An output schema exists, so return shape need not be explained, and a parameterless read tool is inherently simple. The description covers what an agent needs to select it, though it omits session/auth prerequisites that would be relevant in this multi-session toolkit.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies for a parameterless 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?

States a specific verb ('List') and resource ('users currently blocked by the active account'), which is unambiguous on its own. It does not explicitly name sibling tools like bale_block_user or bale_unblock_user, but the read-vs-mutate distinction is self-evident.

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

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

Usage is implied: an agent would call this to enumerate blocked contacts, typically before unblocking one. There is no explicit when-to-use guidance, no mention of prerequisites (e.g., an active session being required), and no exclusions pointing to alternatives.

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

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

No annotations are provided, so the description carries the full burden. 'Fetch' implies a read, but it discloses nothing about pagination, ordering, date-range semantics, permissions, or rate limits — all relevant for a history-listing 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?

A single efficient sentence with the resource front-loaded and no filler. It is concise, though arguably under-specified rather than tight.

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?

An output schema exists so return values needn't be explained, but with zero annotation coverage and four undocumented parameters, the description leaves key calling details (paging, defaults, date semantics) unaddressed for a tool of this complexity.

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

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

Schema description coverage is 0% across four parameters (chat_id, limit, chat_type, offset_date). The description only hints at chat types via 'chat, group, or channel' and says nothing about limit defaults or what offset_date means, so it fails to compensate for the schema gap.

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

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

States a specific verb ('Fetch') and resource ('recent message history') scoped to a chat, group, or channel. An agent can distinguish it from bale_get_dialogs or bale_search_dialogs, though it doesn't name those siblings explicitly.

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

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

No when-to-use guidance, no prerequisites, and no routing to alternatives such as bale_get_dialogs (list chats) or a search tool. The agent must infer that this is for reading messages within an already-known chat.

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 must carry the full burden. 'Retrieve' implies a read-only operation and 'active Bale account' hints at a session requirement, but there is no disclosure of authentication needs, pagination behavior, rate limits, or side effects. It adds some context but leaves significant behavioral gaps.

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?

A single front-loaded sentence with no wasted words. It is appropriately sized for a simple getter and immediately conveys the core action and resource.

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 zero-parameter schema, the presence of an output schema, and the low complexity of the operation, the description is complete enough. Return values are covered by the output schema, so the description need not explain them.

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 the baseline score is 4. The description does not need to explain parameter semantics, and the empty schema is consistent.

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 states a specific verb ('Retrieve') and resource ('list of saved contacts') with scope ('active Bale account'), clearly distinguishing it from write operations like bale_import_contacts. It does not explicitly name sibling alternatives, so it falls short of the highest bar for sibling differentiation.

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?

There is no explicit guidance on when to use this tool versus alternatives such as bale_search_user or bale_get_user_info. Usage is only implied by the tool's name and description, with no conditions or exclusions 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?

With no annotations, the description carries the full burden. It usefully discloses the payload (resolved titles, unread counts, last messages) and 'Retrieve' signals a read operation, but it says nothing about authentication requirements, whether results are paginated, or what offset_date does behaviorally. Partial disclosure only.

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?

A single tight sentence with the resource and return content front-loaded. No filler, though it is arguably too short given the undocumented parameters.

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?

An output schema exists, so return-shape explanation is not required, but the 4 undocumented parameters and absent annotation/usage context leave real gaps for correct invocation (pagination via limit/offset_date, pinned filtering). The description is not sufficient for the tool's parameter surface.

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 0% across 4 parameters, so the description must compensate and largely does not. Only 'resolved' loosely hints at resolve_titles; limit, offset_date, and exclude_pinned are never explained in either place, leaving the agent guessing at pagination semantics.

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

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

States a specific verb ('Retrieve') and resource ('recent chats, groups, and channels') plus the returned fields (resolved titles, unread counts, last messages). This clearly distinguishes it from bale_get_chat_history and the mutation siblings, though it never explicitly contrasts with the closest sibling bale_search_dialogs.

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?

There is no guidance on when to use this versus bale_search_dialogs or bale_list_sessions, nor any mention of prerequisites such as an authenticated session. The 'recent' framing implies a browsing use case, but nothing is stated explicitly.

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 burden; 'Retrieve' implies a read-only, non-destructive operation and it enumerates the categories of data returned, which is useful. It stops short of stating auth/session requirements or any rate/visibility limits, but a return output schema exists so return values need not be elaborated.

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?

A single, front-loaded sentence with no redundant clauses; every listed item (settings, member count, permissions) adds discriminating 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?

An output schema is present so return values are covered, and the read intent is clear, but the one required parameter is undocumented and there is no usage context, leaving modest gaps for an agent to call it confidently.

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 0% and the sole parameter group_id has no description anywhere. The description mentions 'group or channel' but never clarifies that group_id is the identifier for either entity or its expected format, so it does little to compensate.

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

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

States a specific verb ('Retrieve') and resource ('group or channel') plus what is returned: full information, settings, member count, permissions. This implicitly separates it from the sibling bale_get_group_members, though no sibling is named explicitly.

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

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

There is no guidance on when to call this versus alternatives like bale_get_dialogs, bale_get_group_members, or bale_get_user_info, and no prerequisites or session/auth context are mentioned.

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. The word 'permanent' is a meaningful behavioral disclosure distinguishing this link from temporary/expiring invites, and 'get' implies a read-only operation. However, it says nothing about auth requirements, admin privileges, or whether channels vs groups are treated differently.

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?

A single efficient sentence with the resource front-loaded and no filler. It is appropriately sized, though it is perhaps too terse given the undocumented parameter.

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?

An output schema exists, so return values need not be explained, and the tool is a simple single-parameter read. Still, with no annotations and no schema descriptions, the agent is left without auth/prerequisite context that would be needed to call it reliably.

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 single parameter group_id has 0% schema description coverage, and the description adds no clarification beyond saying it works 'for a group or channel'. It is ambiguous whether a channel identifier is acceptable for a parameter named group_id, so the description fails to compensate for the schema gap.

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

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

States a specific verb (get) and resource (permanent invitation link/URL) with scope covering groups or channels. It is clear what it returns, but it does not explicitly distinguish itself from the related sibling bale_invite_to_group, leaving the agent to infer the difference.

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 call this versus alternatives such as bale_invite_to_group or bale_get_group_info. Usage is only implied by the verb; no prerequisites or exclusions are stated.

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 behavioral burden, and it discloses almost nothing beyond the operation itself. It omits pagination/limit behavior, whether channel members are hidden, ordering, and any permission requirements. Only the read nature of the tool is implied by 'Retrieve'.

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?

A single front-loaded sentence with zero wasted words. It is efficient, though its brevity is partly the cause of the gaps noted in other dimensions.

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?

An output schema exists, so return-value explanation is not required, and this is a simple two-parameter read tool. However, with no annotations and 0% parameter coverage, the definition leaves the limit parameter and permission expectations unexplained, which is a meaningful gap for a group-scoped listing tool.

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

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

Schema description coverage is 0% for both parameters. The description implies group_id's meaning via 'in a group or channel' but says nothing about the limit parameter or its default of 50, leaving its paging semantics undocumented in both schema and description.

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

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

States a specific verb+resource: retrieving members of a group or channel. An agent can tell it apart from most siblings (e.g. bale_get_group_info, bale_invite_to_group), though it does not explicitly contrast with them. The purpose is unambiguous but lacks sibling differentiation.

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?

There is no statement of when to use this tool versus bale_get_group_info or bale_get_contacts, nor any prerequisites (e.g. must be a member, admin rights). The agent must infer usage entirely from the name.

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 read-like nature implicitly and notes it also surfaces 'connection status', which is useful context, but says nothing about auth prerequisites, whether it errors when no session is active, or rate limits.

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?

A single front-loaded sentence that identifies both what is returned and the scope (active account) with 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?

For a zero-argument read tool with an output schema defined, the description is nearly sufficient: it names the two result categories (profile, connection status) and constrains scope to the active account, leaving only edge-case behavior (no active session) unstated.

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 takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to clarify about inputs.

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

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

States a specific verb ('Get') and resource ('profile information and connection status of the currently active Bale account'), which is clearly distinct from the sibling bale_get_user_info / bale_search_user that target other users. It does not, however, explicitly name those siblings to reinforce the distinction.

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

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

Usage is implied by 'currently active Bale account' — an agent can infer this is the self-lookup tool — but there is no explicit when-to-use, when-not-to, or pointer to alternatives such as bale_list_sessions (for session/connection detail) or bale_get_user_info.

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 burden, but the verb 'Get' plus an output schema make the read-only nature evident. It adds the field list, yet omits any auth requirements, visibility limits (e.g. non-contacts), or rate-limit behavior, which would be valuable for an un-annotated 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?

A single front-loaded sentence with no filler. The enumerated field list is slightly redundant given an output schema exists, but it does not bloat the definition.

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 one-parameter read tool with an output schema, the definition is minimally adequate — it says what is returned. It still leaves the agent guessing how to obtain a valid user_id and whether authorization or relationship constraints apply.

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 0% for the single user_id parameter, so the description must compensate. Saying 'by user_id' merely restates the parameter name; it gives no format, source (e.g. bale_search_user results, dialog peers), or validity constraints.

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

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

States a specific verb (get) and resource (user profile) and enumerates the returned fields (name, about, username, avatar). It implies a distinction from bale_get_me by requiring a user_id, but never names that sibling explicitly, so an agent must infer the difference.

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

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

Usage is only implied: fetch a profile given a user_id. There is no statement of when to prefer this over bale_search_user or bale_get_me, no note on whether the target must be a contact, and no exclusions.

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

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

With no annotations, the description carries the full behavioral burden, yet it only says 'import'. It does not disclose whether existing contacts are overwritten or merged, how duplicates are handled, whether the call is idempotent, what permissions/auth it needs, or whether the import is all-or-nothing on partial failure.

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?

One short sentence, front-loaded with the action and resource, with no filler. Nothing 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?

Placeholder for contextual_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 description coverage is 0% and the single parameter is a free-form array of objects with no defined item properties, so the description is the only source of meaning. It usefully names the data required (phone number and name) but gives no key names, formats, or per-contact structure, so the agent still cannot construct a valid item reliably.

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 gives a specific verb+resource: importing contacts into the Bale address book. It implicitly contrasts with bale_get_contacts, but never names a sibling explicitly to differentiate read vs. write paths.

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?

There is no guidance on when to use this tool, no prerequisites (e.g., whether an authenticated session is required first), and no mention of alternatives such as adding a contact via another flow. The agent must infer everything from the name.

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 does not state permission requirements, what happens if a user is already a member, whether invitations notify users, or whether the operation is reversible. 'Existing group' hints that the group must pre-exist but nothing more.

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?

A single front-loaded sentence with no filler. It is efficient, though the brevity is partly the cause of the missing detail noted elsewhere.

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 mutation tool with no annotations and 0% parameter coverage, the definition is thin. An output schema exists so return values need not be described, but permission requirements, duplicate-member behavior, and parameter meaning are all absent.

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 0%, so the description must compensate for both parameters. 'One or more users' usefully signals that user_ids accepts a batch, but group_id and the integer ID format are left entirely unexplained. This is far short of what a 0%-coverage, two-parameter tool needs.

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 gives a specific verb (Invite) and resource (users to an existing group or channel), and the word 'existing' implicitly separates it from bale_create_group. It is clear what the tool does, though it never names a sibling for 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?

There is no guidance on when to use this versus alternatives such as bale_get_group_invite_url or bale_create_group, and no stated prerequisites (e.g., caller must be a group admin/member). The agent must infer all usage conditions.

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 behavioral burden and fails to disclose that leaving is irreversible, what happens to chat history or membership, whether the user is removed immediately, or whether admin/ownership constraints apply. It only restates the mutation.

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?

One front-loaded sentence with zero filler. It is efficient, though the brevity reflects under-specification rather than disciplined conciseness.

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?

An output schema exists, so return values need not be explained, but for an irreversible mutation with no annotations and an undocumented parameter the description is far too thin. An agent cannot determine side effects or preconditions for calling it.

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 0%, so the description must compensate and does not: group_id is never explained (ID format, where to obtain it, group vs channel distinction). A single self-evident integer parameter keeps this from being a 1, but nothing beyond the schema is added.

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 states a specific verb (leave) and resource (group or channel), so the agent knows exactly what the tool does. It is not differentiated from siblings such as bale_disconnect or bale_get_group_info, but the action is unambiguous and distinct from those by virtue of the verb.

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?

There is no when-to-use guidance, no prerequisites (e.g. must already be a member), and no mention of alternatives such as bale_disconnect for terminating a session. Usage is only inferable from the verb itself.

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, and it partially does: 'list' implies a non-destructive read and 'stored locally on disk' discloses where the data comes from. It does not explicitly state that this is read-only/safe, what happens if no sessions exist, or that auth is not required, leaving real behavioral gaps.

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?

A single, front-loaded sentence with no filler. Every word contributes to identifying the resource and its scope.

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?

An output schema exists, so return values need not be described, and there are no parameters to document. However, for a session-listing entry point the description omits the workflow context (what to do with the listed sessions) and any usage caveats, leaving it minimally complete.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds nothing further about inputs, but there are no inputs to describe.

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 gives a specific verb ('List') and resource ('Bale user sessions/accounts') plus useful scope ('stored locally on disk'). It is clear on its own, but it never distinguishes itself from the obvious sibling bale_connect_session, so it stops short of full sibling differentiation.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot infer from the text that bale_connect_session is the natural next step after listing, nor when this tool should be preferred over any other session-related call.

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 behavioral burden. It discloses the bulk nature ('all messages'), but says nothing about side effects such as read receipts being sent to other participants, whether unread counters are reset, or what happens if no unread messages exist.

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?

A single, well-formed sentence with the action and scope front-loaded and zero filler. It is efficient, though the terseness partly reflects the missing guidance rather than deliberate compression.

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?

An output schema exists so return values need not be explained, and the operation is simple, but with no annotations and 0% schema coverage the definition leaves an agent without the auth/session preconditions or the chat_type vocabulary needed to invoke it reliably.

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 0% for both parameters. The phrase 'chat or group' loosely hints that chat_type distinguishes private chats from groups, but chat_id format, valid chat_type values, and the default semantics ('private' when omitted) are documented nowhere.

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

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

States a specific verb ('Mark ... as read') and resource ('all messages in a chat or group'), with the scope 'all' made explicit. No sibling tool performs read-marking, so differentiation is implicit, but the action and target are 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?

There is no guidance on when to call this versus alternatives, no prerequisite (e.g. requires an active authenticated session), and no note on whether it applies to a single dialog only. Usage must be inferred entirely from the name and description.

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 behavioral burden for a mutation tool. It does not say whether pinning requires elevated permissions, whether it replaces an existing pin, or what happens if the message is already pinned; 'private chat or group' is the only behavioral nuance offered.

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?

A single short sentence with no wasted words, so structure is fine, but its brevity reflects under-specification rather than efficiency. There is no front-loaded detail to build on.

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?

An output schema exists so return values need not be described, but with 0% param coverage, no annotations, and a mutating operation, the definition is too thin. An agent would need to guess the meaning of just_me and the 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 description coverage is 0% across 4 parameters, so the description must compensate and largely does not. Its phrase 'private chat or group' loosely gestures at chat_type, but chat_id, message_id, and especially the just_me flag are left completely unexplained.

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

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

States a specific verb and resource ('Pin a message') plus a scope qualifier ('in a private chat or group'), so the agent knows the operation. It does not differentiate from any sibling, though no unpin sibling exists, so the ambiguity risk is low.

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?

There is no guidance on when to use this tool, no prerequisites (e.g., admin rights in a group), and no mention of alternatives such as sending or editing a message. The agent must infer the context entirely.

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 mutation but says nothing about whether removal is idempotent, what happens if the reaction isn't present, permission requirements, 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?

A single efficient sentence, front-loaded with the action. Nothing wasted, though there is no room for the missing context.

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

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

An output schema exists so return values need not be explained, but with zero schema description coverage and no annotations, the description leaves the chat_type parameter and all input formats undocumented for a 4-parameter mutation tool.

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

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

Schema description coverage is 0% across 4 parameters. The description names the concepts (emoji, message, chat) but adds no format detail for emoji, no meaning for message_id, and never mentions the chat_type parameter or its 'private' default.

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?

Specific verb+resource: 'Remove an emoji reaction from a message in a chat' clearly distinguishes this from the sibling bale_send_reaction by verb alone. It does not explicitly name the sibling, but the operation is 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?

No guidance on when to use this versus alternatives, no prerequisites stated (e.g. that the reaction must already exist, or that the bot must have permission in the chat). Usage is only implied by the name.

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 notes that only 'active' dialogs are covered, which is a genuine scoping trait, but it says nothing about session/auth requirements, whether results are cached or fetched live, or pagination behavior of the search.

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?

A single front-loaded sentence with no filler. The parenthetical about language support is placed after the core action, which is a sensible ordering, though the term 'active' could be tightened.

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?

An output schema exists, so return-value explanation is not required, and the query semantics are covered. However, with no annotations, 0% schema coverage, and an undocumented limit parameter, the definition leaves too much unsaid for an agent to call it confidently.

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 0%, so the description must compensate. It usefully explains that 'query' accepts a name/title (in Persian or English) or a chat ID, which is meaningful beyond the bare 'string' in the schema, but the 'limit' parameter and its default of 50 are never addressed.

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

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

States a specific verb (search) and resource (active dialogs, groups, conversations) plus the match keys, which distinguishes it from the sibling bale_get_dialogs by implying lookup rather than enumeration. It stops short of an explicit contrast with that sibling, so an agent must infer the boundary.

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

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

Usage is only implied: the mention of matching by name/title or chat ID suggests 'use when you know what you're looking for'. There is no statement of when to prefer this over bale_get_dialogs, nor any prerequisites about an active session.

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 behavioral burden, yet it discloses nothing about result limits, exact-vs-partial matching, or whether the search is scoped to contacts. The existence of an output schema excuses return-value documentation but not these behavioral gaps.

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?

One front-loaded sentence that states the action, the targets, and the lookup keys with zero filler. Nothing could be trimmed without losing meaning.

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

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

For a single-parameter search tool with an output schema, the description covers the essential inputs and target types. It is nearly complete, missing only match-behavior and scope details that an agent would not need to invoke it.

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 0% for the single 'query' parameter, so the description must compensate, and it does partially by stating the accepted forms (username or phone number). It still omits format details such as whether phone numbers need a country code or whether '@' prefixes are expected.

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 gives a specific verb ('Search') and resource ('Bale user, bot, group, or channel') and names the two accepted query forms. It is clear enough to distinguish from bale_search_dialogs, though it does not explicitly contrast itself with that sibling.

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

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

Usage is implied by the input forms (username or phone number), but there is no explicit when-to-use guidance or pointer to alternatives such as bale_get_user_info, bale_get_contacts, or bale_search_dialogs when the agent already knows an identifier.

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 behavioral burden. It implies a write/mutation but discloses nothing about authentication requirements, whether chat_id must reference an existing dialog, rate limits, or error behavior. The only behavioral signal is 'optional reply support', which is thin for a message-sending 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?

A single well-formed sentence with the action front-loaded and no wasted words. It is efficient, though its brevity borders on under-specification rather than true conciseness.

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?

An output schema exists, so return values need not be described. However, for a 4-parameter mutation tool with zero annotation coverage and 0% schema description coverage, the description leaves too much undocumented, especially around chat_type semantics and parameter usage.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It hints at the message body and 'reply support' (mapping loosely to reply_to_message_id), but says nothing about chat_id format, the chat_type default of 'private', or valid chat_type values.

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

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

States a specific verb+resource ('Send a text message') plus the recipient scope (user, group, channel) and reply capability. This clearly separates it from bale_edit_message, bale_forward_message, and bale_delete_message, though it never names a sibling explicitly.

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

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

No indication of when to use this versus alternatives like bale_forward_message or bale_edit_message, and no prerequisites or preconditions. Usage is only implied by the verb.

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 for a mutation tool. It says nothing about idempotency (what happens if the same emoji is already set), permission requirements, whether reactions replace or stack, or rate limits. Only the basic target ('a specific message in a chat') is disclosed.

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?

A single front-loaded sentence with the verb, resource, examples, and target scope. Nothing extraneous and nothing buried.

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?

An output schema exists, so return values need not be explained, but with no annotations and no schema parameter descriptions the definition is thin for a mutation tool. It omits the meaning of chat_type, reaction semantics, and failure conditions an agent would need to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It implicitly covers chat_id, message_id, and emoji (with example values), but leaves chat_type (with its 'private' default) entirely unexplained and gives no format constraint such as whether emoji must be a single character.

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 states a specific verb and resource ('Add an emoji reaction ... to a specific message in a chat') and even gives example emoji, so the action is unambiguous. It doesn't explicitly name the sibling it contrasts with (bale_remove_reaction), but the add/remove distinction is inferable from the verb.

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?

There is no when-to-use guidance, no mention of the bale_remove_reaction alternative, and no prerequisites (e.g., must the user be a chat participant?). The agent is left to infer everything about selection 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?

No annotations are provided, so the description carries the full burden. It does not disclose that this is an ephemeral, non-persistent signal, whether it requires an active session/connection, or any rate-limit behavior. For an action tool with zero annotation coverage this is a significant 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?

A single clean sentence with no wasted words and the action front-loaded. It is efficient, though its brevity borders on under-specification rather than true conciseness.

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?

An output schema exists so return values need no explanation, but that is the only relief. With no annotations, 0% parameter coverage, and no behavioral detail, the description is too thin to let an agent invoke this correctly and safely.

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 0% for both parameters, and the description only loosely gestures at target selection with 'a chat or group'. It does not explain chat_id semantics, nor the meaning or valid values of chat_type (default 'private'), so the 0% coverage gap is not compensated.

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 states a specific verb (send) and resource (typing action indicator) with a target scope (a chat or group), clearly distinguishing it from bale_send_message since it sends a transient indicator rather than content. However, it does not name or contrast with any sibling tool, so it falls short of the top score.

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

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

It states what is sent but gives no guidance on when to use this versus alternatives like bale_send_message, nor any prerequisites such as requiring an active/connected session. Usage is only inferrable from the verb itself.

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 behavioral burden, and it does not say whether the call requires an authenticated session, whether it is idempotent, what happens if the user was not blocked, or what errors are raised. For a mutation tool with zero annotation coverage this is a notable 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?

A single front-loaded sentence that names the action and the target identifier with no padding. It is appropriately sized for a one-parameter tool, though it is too sparse to earn a 5.

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?

An output schema exists, so return-value explanation is not required, and the tool's operation is simple. Still, with no annotations and no error/idempotency behavior described, an agent lacks needed context for edge cases.

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?

One required parameter at 0% schema description coverage, so the description must lean in: 'by user ID' confirms what user_id identifies and that the target is looked up by ID rather than username. That is marginal added meaning over the self-explanatory schema key, but not zero.

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

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

States a specific verb ('Unblock') and resource ('a previously blocked user'), and the unit of identification ('by user ID'). This clearly separates it from bale_block_user and bale_get_blocked_users, though it never names those siblings explicitly.

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

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

Usage is implied by the reverse-of-block semantics; an agent can infer when to call it. However, there is no explicit guidance on prerequisites (e.g., auth/session state) or a named alternative such as bale_block_user, so it settles at implied rather than stated.

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