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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, but the description adds materially: the action cannot be undone, and with revoke it removes messages for everyone rather than just the caller. That is exactly the consequence information an agent needs before invoking a destructive tool.

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

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

Two short sentences, front-loaded with the operation and immediately followed by the irreversibility warning. No filler, though the second sentence packs two separate consequences together.

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 batch-delete with no output schema, the description covers what matters most: irreversibility and the for-everyone scope of revoke. It leaves permission requirements and the confirm gating unstated, but the structured fields cover those.

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

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

Schema coverage is 100%, so the schema documents peer, revoke, confirm, and message_ids on its own. The description restates revoke's global effect ('removes them for everyone in the chat') but adds no syntax, defaults, or constraints beyond what the schema already provides.

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 one or more messages'), so the agent immediately knows the operation and that it is batched over message_ids. It does not explicitly contrast with siblings like edit or forward, but the scope 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?

Usage is implied by the irreversibility warning and the revoke explanation, but there is no explicit when-to-use/when-not or pointer to alternatives such as edit. The 'confirm' prerequisite lives only in the schema, not in the 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?

Annotations already declare the safe, idempotent read profile, and the description adds the non-obvious side effect that a file is written to disk and a path returned rather than bytes inline, plus the reason. It does not cover overwrite/filename behavior or the failure case when a message carries no media.

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

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

Two sentences with no padding: the action and return value come first, then a single-sentence justification of the disk-write design choice. Every clause 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?

With no output schema, the description correctly tells the agent the return value is a local path, and annotations carry the safety profile. Minor gaps remain around naming/overwrite rules and behavior when no media is attached.

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 peer, message_id and dir are already documented, including the working-directory default. The description adds only the return-path behavior, which is not a parameter concern, so 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?

States a specific verb and resource with scope: save the photo/video/document/voice note attached to a message and return the local path. This clearly separates it from send_file and the other message-mutation siblings, though it never names an alternative outright.

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 context is implied by 'attached to a message', and the disk-vs-inline rationale hints at why an agent should prefer this over inlining media. There is no explicit when-not guidance or named alternative, so it stays at implied-usage level.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the mutation is visible to other participants because "Telegram marks it edited," which is a side effect the annotations do not express. It omits failure modes such as edit windows or permission errors, keeping it short of a 5.

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 filler; the core action is front-loaded and the second sentence contributes non-redundant side-effect 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 three-parameter mutation tool with full schema coverage, an explicit safety profile, and no output schema, the description covers ownership scope and the visible edited marker. Nothing critical is missing, though error conditions and edit-window limits are left 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 description coverage is 100% with three documented parameters (peer, message_id, text), so the schema carries the load. The description only gestures at the text parameter and adds no syntax, formatting, or constraints (e.g., length limits or parse modes) beyond what the schema already states.

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 (change) and resource (the text of a message you sent), which implicitly separates it from send, delete, and forward. It does not explicitly name a sibling or contrast with one, so it lands at clear-but-undifferentiated rather than 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?

"A message you sent" is a real ownership constraint that tells the agent this cannot be used on other people's messages, but there is no explicit when-to-use/when-not framing and no routing to alternatives such as send for new content or delete for removal. Usage is 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.

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

Annotations already declare that this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds no behavioral context beyond restating the purpose, such as duplicate handling, permission requirements, rate limits, or what happens to the original 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?

The description is a single front-loaded sentence with no wasted words. It communicates the core action efficiently.

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 three-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description is nearly complete enough to invoke. It omits edge-case behavior such as permission failures or whether messages remain in the source chat, but there is no output schema requiring 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 description coverage is 100%, so the schema already documents all three parameters: from, to, and message_ids. The description adds no extra parameter meaning beyond what the schema provides, so the baseline of 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 states a clear verb and resource: 'Forward messages,' with the scope 'from one chat into another.' It is easy to distinguish from read-only siblings like history and search, but it does not explicitly distinguish itself from write-oriented siblings such as send or edit.

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 guidance about when to use forwarding versus alternatives like send or edit, nor does it mention prerequisites such as needing access to both chats. Usage is only implied by the tool 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?

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds the return-field inventory ('where the chat has them', signaling optional fields), which is mildly useful, but says nothing about failure behavior for an unresolvable peer or any auth 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?

A single efficient sentence with the resource front-loaded and no wasted words. Slightly under-informative rather than over-verbose, which is fine for 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?

No output schema exists, so the description correctly compensates by listing the returned fields and noting they are conditional. Combined with annotations covering the read-only safety profile, this is close to complete for a simple single-record fetch; only error/not-found behavior is 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 description coverage is 100% and the single 'peer' parameter is fully documented in the schema ('A @username, numeric id, or 'me''). The description adds no further syntax or format detail beyond what the schema already provides, so the baseline of 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?

States a specific resource (a single chat) and enumerates the fields returned (name, kind, username, member count, description), so the agent knows exactly what it gets. It does not explicitly distinguish itself from siblings like list_chats or resolve, but 'a single chat' implies a targeted lookup rather than a listing.

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 and no alternatives named, despite several plausible siblings (list_chats for enumeration, resolve for turning an identifier into a chat, history for messages). The agent must infer the selection criteria on its own.

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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new behavioral facts annotations cannot express: results are ordered newest first and bodies are truncated to previews by default, with the rationale for that default. Pagination behavior and response shape are not disclosed, keeping it short of a 5.

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 filler, and the resource plus ordering are front-loaded before the truncation caveat. Every clause carries information the agent 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?

For a read-only tool with a fully documented schema and no output schema, the description covers the essentials an agent needs: scope, ordering, and the preview default. It omits paging guidance (the schema mentions next_cursor) and any hint of the returned message shape, but complexity is low enough that these are minor gaps.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining WHY `full` defaults off — a whole long chat mostly wastes context — which directly informs the most consequential parameter decision. The remaining four parameters get no added meaning beyond their schema descriptions.

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

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

States a specific resource and scope: messages from ONE chat, returned newest first. That verb+resource+ordering is unambiguous and distinct from list_chats/get_chat. It does not, however, differentiate itself from the sibling `search`, which also returns messages, leaving the boundary between browsing one chat and searching all chats to inference.

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 or when-not-to-use statement and no alternative is named, despite `search` being an obvious competing tool for retrieving messages. The only implicit steer is the preview default, which hints at casual browsing rather than targeted retrieval, but this is left unstated.

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 readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds value beyond them by disclosing the return format (compact row per chat with id, name, kind, unread count, preview) and the newest-first ordering.

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 tight sentences with the ordering and return shape front-loaded. Every sentence carries information, though the closing fields tip is somewhat redundant with the schema.

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

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

With no output schema, the description usefully compensates by describing the returned row contents and ordering. It is largely complete for a read-only list tool, with only the sibling-routing context left 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?

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description only reinforces the fields parameter ('Use fields to cut it down further') without adding syntax or format detail beyond what the schema provides, so 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?

States a specific verb and resource ('Recent conversations') and adds ordering ('newest first') plus the returned row shape. It is clear what the tool does, but it never explicitly distinguishes itself from siblings like search, history, or get_chat.

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 phrase 'Recent conversations' implies the browsing use case, but there is no explicit when-to-use guidance, no exclusions, and no named alternatives such as search or get_chat for targeted lookups. Usage is left to inference.

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=false, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds the specific effect (clearing the unread count) but omits auth requirements, rate limits, or what happens on repeated calls. With annotations carrying the safety burden, a 3 is appropriate.

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 filler, and the action is front-loaded. It is efficient, though the brevity also reflects the thin guidance rather than tight editing of rich content.

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 tool with annotations and no output schema, the definition is minimally adequate. It still leaves the when-to-use condition and behavioral specifics (auth, repeat-call effects) 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?

Schema description coverage is 100% for the single 'peer' parameter, so the schema already documents it fully. The description adds no syntax, format, or identifier detail beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb and effect ('Clear the unread count') on a specific resource ('a chat'), so the action is unambiguous. However, it does not differentiate itself from siblings such as get_chat or history, leaving the agent to infer 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?

The description gives no when-to-use guidance, no prerequisites, and names no alternative. An agent gets no help deciding between mark_read and reading the chat via get_chat or history.

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, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds only the notion that the output is an actionable chat entity; it says nothing about failure modes for unresolvable handles or about the lookup cost/latency of an open-world operation.

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

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

Two short sentences; the capability is front-loaded and the usage condition follows immediately. No filler or redundant restatement.

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, idempotent lookup with no output schema and full annotation coverage, the description supplies enough to invoke it correctly. It could go further by indicating what the resolved chat value looks like or how it is consumed by send, since no output schema defines the return shape.

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 'peer' parameter already documents the accepted forms, including 'me'. The description merely repeats those input forms, adding no format or normalization detail 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?

States a specific verb (turn/resolve) and resource (@username, phone, numeric id → a chat), which is a genuine capability statement rather than a restatement of the title. It does not, however, differentiate from lookalike siblings such as get_chat, whoami, or list_chats, which also return chat/user entities.

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?

"Use it before sending to someone you only know by handle" gives a concrete trigger condition tied to the send sibling. There is no statement of when NOT to use it (e.g. when you already have a known chat id) and no named alternative, so it falls short of the explicit when/when-not/alternatives bar.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds the scope-routing behavior but says nothing about result ordering, pagination beyond limit, or rate limits, so it adds only marginal context beyond structured fields.

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 that front-loads the action and resource, then the scoping rule. No wasted words.

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

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

For a simple read-only search with full schema coverage and no output schema, the definition is nearly complete; it covers the one non-obvious behavior (scope when peer is absent). Missing only minor details like result ordering or pagination behavior.

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 all four parameters are already documented in the schema, including the peer-omission semantics the description restates. Baseline 3 is appropriate since the description adds no 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 (search) and resource (message text) plus the scope behavior (one chat vs whole account). An agent can distinguish it from history (browse a chat) and get_chat without needing the schemas.

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?

Clearly explains the condition that switches scope: pass peer to search one chat, omit it to search the whole account. It gives concrete usage context but does not name alternative sibling tools (e.g., history) or state when not to use 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true. The description adds genuinely new behavioral context: the message is 'visible to the recipient immediately' (irreversible external side effect) and 'posts as you' (identity/attribution). It does not mention error cases or that the returned message id feeds reply_to.

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, action stated first, caution second. No filler, no repetition of the title.

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 4-parameter send tool with no output schema, the description covers purpose, visibility, and attribution adequately. Minor gap: it doesn't hint that a message id is returned (useful for the sibling reply_to parameter), but nothing essential 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% and all four parameters (peer, text, silent, reply_to) are documented in the schema itself. The description adds no parameter-level detail, 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?

Specific verb+resource: 'Send a message to a chat.' An agent can distinguish it from siblings like edit, forward, and send_file by the resource named. It stops short of explicitly contrasting with send_file (file vs text) or forward, but the 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?

The closing clause 'only send what was actually asked for' gives an implied usage constraint (don't send unprompted content), but there is no explicit when-to-use guidance and no named alternatives such as edit or forward for modifying/relaying existing messages.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), so the bar is lower. The description adds only that the source file is local, and says nothing about auth requirements, upload/size limits, or failure behavior when the path is invalid — modest added value over the structured fields.

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 filler; the verb and resource lead. It is arguably too terse for the tool's role next to an ambiguous 'send' sibling, but nothing in it 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?

For a low-complexity, 3-parameter tool with full schema coverage, annotations covering the safety profile, and no output schema, the description contains enough to invoke it correctly. Gaps are minor: no mention of upload constraints or error behavior for a bad path.

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% ('Absolute path to the file to send', '@username, numeric id, or me', 'Caption to attach'), so the schema carries full parameter meaning. The description only restates that the caption is optional, adding nothing beyond the schema — baseline 3 is correct here.

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 ('Send a local file'), names the destination ('to a chat'), and notes the optional caption. 'Local file' usefully distinguishes it from the sibling download_media (which moves media the other way), but it does not clarify how it differs from the plain 'send' sibling, which is a real ambiguity for an agent choosing between the two.

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 purpose — an agent reading 'send a local file' knows this is the tool for uploading a file to a chat. However, no when-to-use condition, exclusion, or alternative is stated, and the overlap with the sibling 'send' is left unresolved, so the agent must infer the routing rule.

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, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the useful fact that the identity is session-scoped rather than global, but stops short of describing what the returned account record contains. Compare to the calibration case where annotations covered safety and the description's scoping note earned a 3.

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, zero waste: identity first, then the actionable usage rule. Front-loaded and appropriately sized for a trivial 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?

For a zero-parameter, read-only, idempotent lookup with annotations carrying the safety profile, nothing an agent needs in order to call it correctly is missing. The lack of an output schema is the only minor 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 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?

States a specific resource and scope: the Telegram account the current session is signed in as. It is immediately distinguishable from every sibling (send, edit, history, etc.), none of which deals with session identity.

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?

"Call it first when it matters whose messages you are about to read or send" gives an explicit triggering condition and an ordering instruction. It does not name any alternative or exclusion, but for an identity tool no plausible alternative exists.

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