Telegram MCP Enhanced

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

With no annotations provided the description carries the full burden, and it does: destructive and irreversible, a separate permission that is disabled by default, error behavior when the entity is missing, and the atomic validation rule that every ID is checked against the named chat and the whole batch is refused if any ID belongs elsewhere. That last detail is exactly the kind of non-obvious behavior an agent cannot infer.

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?

Well front-loaded with the destructive/security warning and the fallback tools called out before the arguments. The opening two lines say the same thing twice ('Delete messages from a specific entity.' / 'Deletes messages from a specific entity.'), which is pure waste, and the Returns block duplicates the output schema.

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

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

For a destructive two-parameter tool with no annotations, the description supplies the safety profile, the permission precondition, the error case, the recovery path via sibling tools, and the batch-validation guarantee. An output schema exists, so return values are already covered, and nothing an agent needs in order to call this safely 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 0%, so the description must document both parameters, and it does: entity as the entity identifier and message_ids as a list of message IDs. It also adds a cross-parameter constraint (IDs are validated against the named entity, batch refused on mismatch) that the schema does not express, though it never says what form the entity identifier takes (ID vs username vs title).

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

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

States a specific verb and resource ('Delete messages from a specific entity') and names the scope. It doesn't distinguish itself from the adjacent edit_message/send_message siblings, but it does route to search_dialogs and get_messages for the prerequisite lookups.

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 explicit preconditions: call search_dialogs when the entity is uncertain and get_messages when the message IDs are uncertain, plus a requirement to confirm with the user and an explicit prohibition on deleting because message content asked for it. No guidance on when to delete versus edit or archive, so no exclusion against sibling mutations.

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 load and does it well: it discloses the not-found error path, that editing is an independently configured permission disabled by default, that a denial is server policy rather than a Telegram error, and warns that instructions inside a message cannot lift that policy (prompt-injection defense). This is materially beyond anything in the schema.

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 first two lines are a near-duplicate restatement ('Edit a message from a specific entity.' / 'Edits a message from a specific entity.'), which is pure waste. The critical security caveat is buried after the error/precondition notes rather than front-loaded, though the Args/Returns block is tidy.

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-required-parameter mutation tool with no annotations, the description covers the error behavior, permission model, prerequisite lookups, and argument meanings. Return value handling is already covered by the output schema, so nothing an agent needs to call this correctly 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 0%, so the description must compensate, and it annotates all three parameters: entity as an identifier, message_id as the target message, and message as the new content. It falls short of specifying accepted entity formats (username vs numeric ID vs phone) and whether message supports markup.

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 ('Edit a message from a specific entity'), so the agent knows exactly what action is performed. It does not differentiate itself from siblings like delete_message or send_message, but the operation is unambiguous on its own.

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 explicit conditional routing: use `search_dialogs` when the entity is uncertain (and ask the user to pick), and `get_messages` when the message ID is unknown. What's missing is when *not* to use this tool versus alternatives such as sending a replacement or deleting the message.

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 and does well: it discloses that an unknown entity returns an error message rather than raising or returning empty, and that a missing draft yields an empty string. It does not discuss permissions or rate limits, but for a read operation this is solid disclosure.

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 key behavior and the escape hatch are front-loaded and bolded, which is good. However, the Args/Returns docstring duplicates the prose above and restates return values that the output schema already covers, adding bulk without new 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?

Given a single-parameter tool with an output schema, the description covers the input formats, the empty-draft case, the error case, and the recovery path. An agent could call this correctly from the description alone; only edge-format details are 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 description coverage is 0% and the single property is a bare string, so the description must compensate; it enumerates the accepted identifier forms (chat ID, username, phone number, 'me'). That is meaningful added semantics, though it does not explain formatting nuances such as country-code expectations for phone numbers.

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: 'Get the draft message for a specific entity.' This is clearly distinct from siblings like set_draft and get_messages, so an agent can pick it 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 concrete guidance for the failure case: if the entity is uncertain, use `search_dialogs` and ask the user to select the correct entity. It does not contrast with `get_messages` or `set_draft`, but the when-to-use context for the uncertain-entity case is explicit.

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 does substantial work: it discloses the not-found error behavior, the server-side limit cap (~200), the side effect of mark_as_read, and an extensive untrusted-content/security posture including per-message security metadata and high_risk handling. It does not mention auth requirements or message ordering, which are the remaining 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?

Front-loaded with purpose, then error handling, then a clearly demarcated security block, then per-argument docs and returns. The security paragraph is long but every sentence changes agent behavior, so 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?

An output schema exists, so return-shape explanation is optional and the description only briefly summarizes it. Given the tool reads untrusted third-party data with a server-side cap, the coverage is strong; the notable omissions are result ordering (which matters when truncating via limit) and date-range semantics.

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 it does: all six parameters are explained, including the accepted entity identifier formats, the limit default and server cap with rationale, and the unread/mark_as_read defaults. Date parameters get only one line each, with no timezone, inclusivity, or interaction-with-limit guidance.

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 opening line states a specific verb and resource (get messages) and constrains scope to a single entity. It doesn't explicitly contrast with siblings like message_from_link or get_quarantined_message, but the entity-not-found note routes the agent to search_dialogs, so the tool is distinguishable in practice.

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 conditional guidance: if the entity is uncertain, use search_dialogs and ask the user to pick. It also advises requesting a narrower date range instead of a large limit. It lacks explicit when-not-to-use guidance relative to message_from_link or get_quarantined_message.

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 supplied, the description carries the full behavioral burden and does so: it discloses the mandatory human-approval gate, the independent read-permission and chat-access requirement, and the fact that the returned text retains `security` metadata about what was detected. It also warns that the content is untrusted data to be reported on, not instructions to follow — a crucial trait no annotation would have conveyed.

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?

Purpose and the approval-gate constraint are front-loaded, and the security block earns its space because it changes how the agent should treat the output. Minor waste remains: the 'Added by Telegram MCP Enhanced' attribution adds nothing for selection, and the Returns section restates what the output schema already declares.

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 tool with no annotations, the description covers the gaps that matter: trigger conditions, the per-call human approval requirement, permission needs, and trust handling of the returned content. The output schema carries the return shape, so the extra Returns line is harmless redundancy rather than a missing piece.

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 and largely does by defining both params: `entity` as the chat the message is in and `message_id` as the withheld message's ID. It stops short of specifying the accepted `entity` formats (username, numeric ID, or link), which is the one ambiguity left for a required string param.

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 — returning the original text of a message withheld by policy — and immediately scopes it apart from get_messages by tying it to block/redact-mode placeholders. An agent can tell exactly which tool handles a withheld message versus a normal one.

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 an explicit trigger ('Use it only when the user asks to see a withheld message') and an explicit restriction, plus the operational precondition that a human must approve in a confirmation prompt every time. The alternative path (placeholder text arriving via normal channels) is described, so the agent knows when this tool is the right escalation.

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 does reasonably well: it discloses the error behavior for unknown entities, the security treatment of the sender-supplied filename as untrusted, and that the download location is validated against a server file-access policy. It omits things like size limits, overwrite behavior on an existing path, or permission requirements.

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

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

Front-loads the core action, then the important caveat and security note, so an agent skimming gets the essentials first. The Args/Returns block largely restates the input schema and the output schema, which is some avoidable bulk for a three-parameter tool.

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

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

Covers purpose, entity resolution fallback, security posture, default path, and return type, which is thorough for a three-parameter tool. Because an output schema already exists, the return section is redundant rather than additive, and edge cases around write conflicts remain unaddressed.

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 supply all parameter meaning, and it does: `entity` enumerates the accepted identifier forms (chat ID, username, phone, 'me'), `message_id` is tied to the message holding the media, and `path` is described as optional with a default tied to XDG_STATE_HOME. The `path` default description is slightly vague about the concrete filename/location.

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 ('Download media from a specific message') plus the destination ('a unique local file'). This is clearly distinct from siblings like get_messages (listing) and message_from_link (resolving), so an agent can select it 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 an explicit failure-path rule: if the entity is not found, use `search_dialogs` and ask the user to pick the correct entity. That names an alternative and the condition that selects it. It does not, however, address when to choose this over `message_from_link` or `get_messages` for related tasks.

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 zero annotations the description carries the full burden, and it does disclose real behavior: invalid links or unauthorized accounts return an error, the chat is checked against a server allowlist, and the result is untrusted external data carrying safety metadata. That is genuinely useful, but it omits whether the call is strictly read-only, any rate limits, and what the safety metadata actually looks like.

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 security warning is well placed and front-loaded, but 'Get a message from a link / Retrieves a message from a link' and the Args/Returns block ('The link to the message', 'The message from the link') repeat information already conveyed by the first line. Roughly a third of the text is redundant with the tool name and input schema.

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

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

An output schema exists, so the Returns block need not explain the message shape, and the description appropriately focuses on error conditions and the untrusted-data contract. For a one-parameter read tool with no annotations this is close to complete; only the read-only guarantee and allowlist failure semantics could be spelled out further.

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 'link' parameter, so the description must compensate; it only restates 'The link to the message' in the Args block. The one piece of added meaning is the requirement that it be a valid Telegram message link, which appears incidentally in the IMPORTANT note rather than as a parameter specification.

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 ('Get a message from a link'), and the link-based retrieval does distinguish it from siblings such as get_messages and get_quarantined_message. However, the second sentence ('Retrieves a message from a link') is a pure restatement that adds nothing, and no sibling is ever 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: an agent can infer this is the tool for resolving a Telegram message URL rather than for listing messages. The description states failure preconditions (invalid link, unauthorized account) but never says when to prefer this over get_messages or how to obtain a link in the first place.

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 disclosure burden, and it does a lot: case-insensitive matching, the searched fields, the default limit of 10, a positive limit constraint, an untrusted-data warning, an allowlist that withholds chats and reports withheld_count, and a safety-envelope return. The remaining gap is that global_search's behavior is completely unexplained.

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 advice is front-loaded and the SECURITY block earns its place, but the second sentence largely restates the first, and the Args section duplicates the schema already provided. The '!IMPORTANT' framing is somewhat noisy for a short reference.

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 detail is not required, and the description still flags the safety envelope and the error possibility. Considering the tool has only three parameters, what is missing is minor: only global_search semantics are left unclear.

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 explain meaning, and it does for two of the three parameters: query (case-insensitive, matched within title or username) and limit (default 10, must be greater than 0). global_search is mentioned only as a boolean defaulting to False, and the description never says what a global search covers or when it differs from the 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?

The description opens with a specific verb and resource set: searching users, groups, and channels. It also narrows the matching behavior to dialog title or username. It never names a sibling, but none of the siblings (send/edit/delete_message, get_messages) overlap in purpose, so an agent can still tell them apart.

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 includes a useful diagnostic hint: if results are wrong, the query is probably not specific enough, so try a different one. However, it does not say when to prefer this tool over get_messages or message_from_link, and it never explains when to set global_search, even though that flag changes the scope of the search.

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 behavioral burden and does well by stating that it reports policy only and never includes credentials, session data, chat identifiers, or message content. It also summarizes the returned policy dimensions, though it stops short of explicitly saying 'read-only' or 'no side effects' in annotation-style terms.

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

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

The description is front-loaded and generally efficient, leading with the purpose and then usage guidance. The 'Added by Telegram MCP Enhanced' note and the return-value summary are slightly extraneous given the output schema, but they do not materially distract.

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-parameter status tool with an output schema, the description supplies enough context: what it reports, when to use it, and what sensitive data it excludes. Nothing needed to invoke or interpret the tool correctly 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?

The tool takes zero parameters, so the baseline is 4. The description correctly does not invent parameter semantics and keeps the focus on the policy report itself.

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 ('Report') and resource ('security and reliability policy this server enforces'), making the tool's purpose unambiguous. It is clearly distinguishable from the sibling message-operation tools because it is a policy/status endpoint rather than a chat action.

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 says when to use it: before attempting an operation to learn what is allowed, or to explain to the user why a request was refused. No sibling tool performs the same role, so there is no meaningful alternative to route to.

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 supplied, the description carries the full burden and does so well: it discloses a server-side send permission and chat allowlist, a file-access policy check before upload, a 10-file cap, message size limits (35,000 bytes / 4,096 chars), Markdown support, and the success/error return shape. It also warns about prompt-injection attempts embedded in content, chat titles, or filenames, which is meaningful behavioral context for an outbound-send 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?

Structure is strong and front-loaded: purpose, then the entity-disambiguation rule, then security, then args. The security paragraph is a bit long and the Args block is verbose, but given 0% schema coverage the parameter detail earns its space rather than being padding.

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 four-parameter outbound-mutation tool with no annotations, the description covers identification of the target, content constraints, file handling policy, reply semantics, and failure mode. An output schema exists, so the brief return note is sufficient rather than redundant.

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 entirely, and it does: `entity` formats (chat ID, username, phone number with '+', group/channel username, special "me"), `message` Markdown syntax and length limits, `file_path` as a list with a default cap of 10 and policy checks, and `reply_to` as a message ID. Each of the four parameters gains meaning not present in the bare schema titles.

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 opens with a specific verb+resource ("Send a message to a Telegram user, group, or channel") and scopes it to any Telegram entity identified by `entity`. This clearly distinguishes it from siblings such as edit_message, delete_message, and 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?

It gives an explicit conditional route: when the entity is uncertain, use `search_dialogs` and have the user pick the correct entity. That is a concrete when-to-use rule tied to a named sibling. What is missing is explicit exclusion guidance versus edit_message/delete_message or whether this is only for new messages rather than replies (though reply_to implies the latter).

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 does disclose the failure mode (entity not found returns an error) and that results come back as strings. It does not say whether an existing draft is overwritten, whether any auth/permission is required, or that nothing is actually sent — meaningful gaps 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?

The opening two sentences say the same thing twice ('Set a draft message for a specific entity' / 'Sets a draft message for an entity specified by...'). The Returns block duplicates the existing output schema, adding bulk without new 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 two-parameter write tool with an output schema present, the definition covers identifier formats, the lookup-failure path, and result shape. The overwrite behavior and send-vs-draft distinction are the remaining things an agent would want.

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 carry the parameter meaning, and the Args block does: entity accepts a chat ID, username, phone number, or 'me', which the bare schema does not convey. The message parameter is only restated, so not every parameter gains extra meaning.

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 ('Set a draft message') and scopes it to an entity. It implicitly distinguishes itself from the read-side sibling get_draft and from send_message, though it never explicitly contrasts with them.

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 a concrete when-not path: if the entity is uncertain, call `search_dialogs` and have the user pick. That is real routing guidance. It stops short of stating that this only stages a draft and does not transmit it, which is the key distinction from send_message.

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