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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description must carry the rest. It does not say whether the code is single-use, what happens on an incorrect code, whether a 2FA password step follows, or what a successful submission yields.

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 its brevity contributes to the missing flow context rather than making room for it.

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 full schema coverage, the basics are covered. However, an authentication step in a multi-tool flow benefits from noting the expected sequence and outcomes, and there is no output schema to fill that gap.

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

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

Schema description coverage is 100% and already explains that the value is the Telegram login code with digits sometimes containing letters. The description adds only the framing that the code was sent to the account, which is marginal beyond the schema.

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

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

States a specific verb+resource: submitting the login code Telegram sent. That is clearly distinct from auth_password, auth_start, and auth_status without needing the schema. It stops short of naming that distinction 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 auth_password or auth_start, nor any prerequisite such as having called auth_start first. An agent must infer the position of this step in the auth flow 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?

Annotations already flag destructive and open-world behavior; the description adds that all local session data is destroyed, network access is required, and re-login is needed to recover. This is useful context beyond the annotations, though it does not detail server-side session invalidation or confirm-flag behavior.

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

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

Two front-loaded sentences with no filler; destructive scope and reversibility are communicated efficiently. Every sentence adds 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 one-parameter destructive logout, the description supplies the key operational facts: what is destroyed, network dependency, and irreversibility. The schema handles the confirmation parameter, and no output schema requires return-value explanation.

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

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

Schema coverage is 100% and the single required confirm parameter is fully documented in the schema. The description adds no parameter-specific meaning, such as what happens if confirm is false, so it meets the baseline only.

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 action, 'Log out,' and scope, 'destroy all local Telegram session data,' clearly distinguishing it from auth_start, auth_status, auth_code, and auth_password. An agent can identify this as the session-termination tool without inspecting the schema.

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 implies use when ending a session and notes network access and irreversibility, but does not explicitly say when to choose this over auth_status or auth_start, nor does it state when not to use it. Guidance is present but mostly inferred.

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

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

Annotations declare readOnlyHint=false and openWorldHint=true, so the mutating, externally-dependent nature is already visible. The description usefully adds the conditional 2FA requirement, but says nothing about failure behavior for an incorrect password, attempt limits/flood waits, or the effect on session state, which matter a great deal for an auth credential submission.

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 with the action front-loaded and the only meaningful condition attached. Nothing redundant and nothing that could be trimmed without losing information.

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

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

For a one-parameter tool with full schema coverage and no output schema, the description covers what it does and the key precondition. The remaining gap is flow placement relative to auth_start and auth_code and error handling, which are useful but secondary for a tool this simple.

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

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

There is a single parameter with 100% schema description coverage, so the schema already explains that it is the Telegram two-step verification password. The description adds no format, source, or handling guidance beyond that, which is the expected baseline when the schema does the work.

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 names a specific verb (submit) and a specific resource (the two-step verification password), which clearly separates it from siblings such as auth_code (login code) and auth_status. It stops short of explicitly naming those siblings as alternatives, so it is clear but not maximally differentiated.

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 clause 'if the account has one enabled' gives a real precondition, which is more than most definitions offer. However, it never states where this sits in the auth flow (after auth_start/auth_code), how to determine whether 2FA is enabled, or what to do if submission fails, so the agent must infer sequencing.

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

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

The annotations already mark this as non-read-only and open-world. The description adds important behavior: Telegram sends a login code to the account and the flow continues through auth_code and auth_password when 2FA is enabled. It does not cover failure cases, rate limits, or session side effects, but it provides strong workflow context beyond the annotations.

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

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

The description is short, front-loaded with the action, and every sentence contributes either the side effect or the required follow-up calls. There is no unnecessary wording.

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

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

For a login-start tool with annotations and a fully documented single parameter, the description covers the essential action, side effect, and next steps. Because no output schema exists, it could say more about what auth_start returns, but the workflow guidance is otherwise complete.

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

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

Schema description coverage is 100%, and the single phoneNumber parameter is fully documented in the schema with an international format example. The description only refers to 'phone-number login' and adds no format or validation detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Start phone-number login.' It also distinguishes this step from the sibling tools auth_code and auth_password by explaining the sequence.

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

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

It explicitly states when to use this tool and names the follow-up tools: call auth_code after receiving the code, and auth_password if two-step verification is enabled. This gives clear sequencing with no ambiguity about the next step.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully signals that the response indicates which login step is required, but it does not enumerate the possible steps or explain what a signed-out result looks like, so the agent must infer the recovery path.

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

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

Two short sentences with no waste: the capability comes first and the usage trigger second. Nothing is redundant or 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?

With no output schema and no annotations explaining returns, the description carries the burden of telling the agent what comes back, and it does so at a high level (signed-in flag plus required login step). Naming the concrete step values would close the remaining gap for this small diagnostic tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies a parameterless status probe and adds no misleading argument expectations.

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

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

The description states a specific check (whether the Telegram session is signed in) and an additional output (which login step is required). It is clearly distinct from the mutating siblings auth_start, auth_code, auth_password and auth_logout, though it does not name them 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?

It gives an explicit entry condition: 'Start here if Telegram tools return an authentication error.' That tells the agent when to reach for this tool, but it does not say when to skip it (e.g. once already signed in, proceed directly to discover_chats).

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds genuinely new behavioral facts: returns metadata only and never message contents, and requires a config flag to be enabled. The main remaining gap is nothing about result ordering or whether the underlying chat list is fetched live from Telegram each call.

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

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

Three short sentences, each carrying distinct information: purpose, safety/scope, prerequisite, and usage mode. The most decision-relevant content (what it returns and what it does not) is front-loaded 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 two-parameter read-only tool with full schema coverage and no output schema, the description covers purpose, return content, precondition, and both usage modes. Minor omissions like ordering or whether limit applies to search results are not described, but nothing critical to a correct call is 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 coverage is 100%, so both parameters are already documented, but the description adds the meaningful default behavior that omitting the query switches the tool from search to top-chats listing. That semantic (mode selection via presence/absence of a param) is not conveyed by the schema alone.

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

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

The description gives a specific verb and resource ('List chat ids and titles') plus the intent ('to help populate the allowlist') and an explicit scope boundary ('metadata only, never message contents'). It does not name the sibling it is distinguished from (list_allowed_chats), so the differentiation is implied rather than stated.

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 two clear usage modes: pass a query to search, or omit it to list top chats, and it discloses the prerequisite that allowChatDiscovery must be enabled in config.json. It stops short of explicitly excluding cases where get_chat or list_allowed_chats would be the better 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and reach profile is covered externally. The description adds the meaningful constraint that only allowlisted chats are retrievable and, since no output schema exists, lists the fields returned. It does not say what happens on a non-allowlisted or unknown chat (error vs empty result), which is the main remaining behavioral 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?

One sentence, front-loaded with the verb and resource, with the return-field list appended where it is most useful. No redundant or filler wording; it stops slightly short of being fully self-contained rather than being padded.

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 read tool this is nearly complete: the parameter is fully documented and, with no output schema, the description usefully names the return fields. The only missing piece an agent might want is failure behavior for chats outside the allowlist.

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

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

Schema coverage is 100% and the single 'chat' parameter already documents the accepted formats (@username, t.me link, numeric id, exact title). The description restates 'allowlisted chat' without adding format or resolution guidance beyond the schema, so the baseline 3 applies.

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 ('Get details about') and a precisely scoped resource ('one allowlisted chat'), then enumerates the returned attributes (title, type, username, member count, description). The 'one' contrast against the sibling list_allowed_chats is implied but never stated outright, so it falls just 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?

Usage is only implied: an agent can infer this is the single-chat lookup as opposed to the bulk list_allowed_chats or the message-oriented get_messages, but nothing in the text says when to prefer one over the other. There are no stated prerequisites or exclusions beyond the 'allowlisted' qualifier.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds one genuinely useful constraint — the chat must be allowlisted — but says nothing about what happens when the id or chat is not allowlisted, nor about error/no-result behavior.

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

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

A single front-loaded sentence with no filler; the resource, the lookup key, and the access constraint are all stated up front.

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 two-parameter read with full schema coverage and no output schema, the definition is minimally sufficient — an agent knows what to call and how. It stops short of describing failure modes (non-allowlisted chat, unknown message id) that would matter for a tool restricted to an allowlist.

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

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

Schema description coverage is 100%, and both parameters (chat formats, messageId bounds) are already documented in the schema. The description adds no format or semantics beyond that, so the baseline 3 applies.

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 names a specific verb and resource ("Fetch a single message by id") and narrows scope to "an allowlisted chat." The word "single" implicitly separates it from the bulk sibling get_messages, 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?

Usage is only implied: retrieving one message by id vs listing via get_messages or querying via search_messages. There is no explicit when-to-use/when-not clause and no statement of prerequisites beyond the passing mention of the allowlist.

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

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

Annotations already establish this as a safe read (readOnlyHint) against an open system (openWorldHint). The description adds meaningful behavior beyond that: results are ordered oldest first and paging is backward-only via a cursor, which shapes how an agent must consume the results. It does not state what the response contains (notably whether nextBeforeMessageId is returned) or what happens for a non-allowlisted chat.

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

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

Two sentences, zero waste. Scope and ordering come first, then the paging mechanic, which is the order an agent needs them.

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

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

With no output schema, the description should ideally confirm that the response carries nextBeforeMessageId, since the whole pagination workflow depends on it. Otherwise it covers scope, ordering, and paging adequately for a small read-only tool whose parameters are fully documented.

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

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

Schema coverage is 100%, with chat formats, limit bounds, sinceDate formats, and the beforeMessageId cursor all documented inline. The description's pagination sentence restates what the schema already says about nextBeforeMessageId, so it adds little parameter meaning beyond the structured fields.

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 (read messages), scopes it to one allowlisted chat, and states the ordering (oldest first). It is clearly distinct from get_message (single message) and search_messages (query-driven), 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?

Context is clear: use for recent history of a single allowlisted chat, and use the beforeMessageId/nextBeforeMessageId loop to walk backwards. There is no explicit routing statement about when to prefer search_messages or get_message instead, so the guidance stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral detail beyond that: entries may carry resolution errors, implying partial/failed lookups rather than a clean list. It says nothing about ordering, pagination, or how entries enter the allowlist.

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 sentence with zero filler, front-loading the action and then the payload. Nothing is repeated from the title or annotations.

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

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

With no output schema, enumerating the returned fields is a valuable addition that partially compensates. However, the description never explains what the allowlist is, how it relates to discover_chats, or what a resolution error means for the caller — gaps that matter for a zero-param tool whose result shape is otherwise 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?

The tool takes zero parameters, so there is no parameter semantics to convey and the baseline of 4 applies. The description correctly implies the call is unfiltered and unscoped.

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?

"List every chat in the allowlist" is a specific verb plus resource, and the trailing clause names the returned fields (ids, types, usernames, resolution errors). It stops short of distinguishing itself from the sibling discover_chats, so an agent cannot tell from the description alone which listing tool applies.

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 and no named alternative, even though discover_chats and get_chat sit right beside it in the sibling list. The agent must infer from the name that this returns the allowlisted subset rather than discovered or individual chats.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: the allowlist restriction and result ordering ("newest first"). It does not address pagination behavior, matching semantics (substring vs token), or whether results are ranked vs purely chronological beyond the ordering note.

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

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

Two short sentences with zero waste: scope first, ordering second. Nothing is padded and nothing needs to be read twice.

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 three-parameter read-only search with full schema coverage and no output schema, the definition covers scope and ordering adequately. A brief note on result fields or matching behavior would close the remaining gap.

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

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

Schema description coverage is 100%, with chat, limit, and query all documented in-schema, so baseline is 3. The description restates the chat-omission rule already present in the schema and adds nothing about query matching or limit interaction.

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?

Names a specific verb and resource ("Search messages by text") and states the scope precisely: one allowlisted chat or all allowlisted chats. That scope distinction is what separates it from get_messages, but the description never names or contrasts with that sibling, 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?

Gives usable context (omit chat to search everything) which tells the agent how to broaden scope, but offers no explicit when-to-use versus get_messages or get_message, and no exclusions or prerequisites besides the implicit allowlist constraint.

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?

Goes well beyond the annotations by disclosing the human-in-the-loop approval prompt showing exact chat and text, the failure return shape ('sent: false' on decline), and the config prerequisite. These are the details an agent needs to avoid blind retries and to explain outcomes to the user.

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

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

Four short sentences, front-loaded with the action and scope, followed by the prerequisite, the approval behavior, and the retry rule. No filler or repetition.

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?

There is no output schema, so the description supplies the key return semantics ('sent: false' if declined) along with the approval gate and config dependency. For a four-parameter mutation tool with annotations, nothing an agent needs before calling is 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 100%, so chat formats, the 4096-character bound, replyToMessageId, and disableNotification are already documented. The description only reinforces 'plain-text' and the single-allowlisted-chat constraint, adding little parameter-level meaning beyond the schema.

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

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

States a specific verb and resource ('Send a plain-text message') plus the scope constraint ('to one allowlisted chat as the signed-in user'), which immediately separates it from the read-oriented siblings like get_messages and search_messages. An agent can identify the operation without opening the schema.

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?

Gives clear preconditions ('Requires allowSending in config.json') and an explicit when-not-to rule ('Do not retry a declined message unless the user asks'). It does not name a sibling alternative, though the sibling list contains no other write tool, so the omission is minor.

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