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

Goes beyond the annotations by disclosing the 20 MB Bot API ceiling and that the call produces a local file path. Annotations only mark it non-readOnly/openWorld; the description supplies the practical constraint that determines success or failure. It doesn't say where the file lands or how failures/oversized files surface.

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, leading with the action and ending with the return value. Every clause carries information an 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?

With one parameter, no output schema, and a 20 MB limit disclosed, the description covers what an agent needs to invoke the tool and interpret the result. Only edge-case behavior (oversized file, missing file_id) is left implicit.

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 sole parameter already says 'file_id from an incoming message'. The description repeats the parameter name and constraint but adds no format or sourcing detail beyond the schema, 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 ('Download a file from Telegram by file_id') and implies the returned artifact ('its local path'). It is clearly distinguishable from the send_* siblings, 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?

The tool is single-purpose enough that when-to-use is obvious from the name and from the fact that all siblings are send/kill/health tools. There is no explicit statement about when not to use it or what alternative to pick for oversized files.

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

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

Discloses the most important non-obvious trait: a default call acknowledges (consumes) unseen updates, so an agent knows repeat calls can lose messages, and offset: 0 is the escape hatch. This adds genuine value beyond the readOnlyHint/openWorldHint annotations. Minor tension: 'acknowledged' implies a cursor-advancing side effect that readOnlyHint=true does not advertise, but the description is the more accurate of the two and no return/blocking behavior is described.

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

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

Two tight sentences, zero filler. The default/consumption behavior leads, and the offset: 0 workaround follows immediately where it is needed.

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, and the description says nothing about what an 'update' contains or how results are shaped, which an agent needs in order to parse the response. For a 3-parameter, no-output-schema fetch tool with annotations present, the description is adequate but leaves that gap open.

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, and the description earns an extra point by adding offset semantics the schema lacks (offset: 0 re-reads the backlog, vs. omitting it to continue). limit and timeout get no narrative treatment, but their schema descriptions are already sufficient.

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 concrete verb+resource ("Fetch recent incoming messages") that an agent can immediately map to an operation, and it is implicitly the only read-side tool among send/download siblings. It stops short of naming a sibling or stating the inbox/polling role explicitly, 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?

Gives usable operating context: default behavior returns only unseen updates, and offset: 0 forces a backlog re-read. That is a real when-to-use signal, though it never states when NOT to call it (e.g., rate limits, or that repeated default calls advance the cursor past 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 readOnlyHint and openWorldHint, so the description needn't re-explain the safety profile. It adds value by disclosing what the call returns (bot id, username, capabilities), which matters because there is no output schema; it does not mention auth prerequisites beyond the token itself or failure behavior on an invalid token.

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

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

One short sentence, front-loaded with the action and then the return payload. Every clause earns its place with no filler.

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

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

For a zero-parameter diagnostic tool with no output schema, the description covers purpose and return contents, which is enough for an agent to call it correctly. Adding a note about what happens on an invalid token would round it out but isn't essential.

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 and the schema carries nothing to document. The description correctly adds no parameter discussion because none are needed.

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 (check bot token) and enumerates the result (bot id, username, capabilities), which clearly separates it from the send_* and get_updates siblings. It doesn't name those siblings, so differentiation is implied rather than explicit.

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?

"Check that the bot token works" implies a pre-flight/credential-validation use case, which is enough for an agent to infer when to call it. There is no explicit when-not guidance or named alternative, so usage is only implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the description's job is supplemental. It does add real value beyond them: the 50 MB cap and the fact that the source may be either a local path or a fetched public URL (which explains the openWorld hint). It stops short of saying what happens on oversized or unreachable files, but that is a minor gap given 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?

Two tight sentences: the core action and constraints come first, supported use cases second. No repetition of the name or schema fields, and every clause carries 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 four-parameter send tool with full schema coverage, annotations, and no output schema, the description covers action, input forms, and size limit. What is missing is failure behavior and the file-vs-photo boundary, both minor 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?

Schema description coverage is 100%, so the schema already documents all four parameters, including the TELEGRAM_DEFAULT_CHAT_ID fallback and the caption length limit. The description only reinforces file_path semantics (absolute path or public URL) and adds the size limit; it says nothing about parse_mode or caption behavior beyond what the schema states. 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 ('Send a document/file') plus the accepted input forms (absolute local path or public URL) and a size ceiling (max 50 MB). It implies the boundary with telegram_send_photo and telegram_send_message by naming documents/files rather than messages or images, but never explicitly routes the agent away from those siblings.

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 use-case list ('build logs, diffs, screenshots and reports') gives implied context for when this is the right tool, but there is no explicit when-not guidance and no mention of telegram_send_photo as the alternative for images — notable since 'screenshots' is listed as a use case here.

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, so the safety profile is covered. The description usefully adds the 4096-character rejection limit and the supported parse modes, but says nothing about rate limits, error behavior, or what the call returns.

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, front-loaded with purpose, then capabilities, then a hard constraint that prevents a failure mode. 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 simple three-parameter send tool with annotations and a full-coverage schema, the description plus structured fields give an agent everything needed to invoke it correctly. Only rate-limit/error and return-value expectations are absent, which is minor for a mutation with no output schema.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the escape rules for MarkdownV2 and the default chat_id fallback. The description reinforces the length constraint on text but adds no new per-parameter semantics; 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 clear verb and resource ("Send a text message to a Telegram chat") and the word "text" implicitly distinguishes it from telegram_send_photo and telegram_send_file. It never names those siblings explicitly, so differentiation is inferential 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?

Sending a text message is the obvious implied use case, and the 4096-character note implies "split instead of calling this." But there is no explicit routing to alternatives (send_photo/send_file) or statement of prerequisites such as needing a valid chat_id or bot permissions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds a useful behavioral constraint (max 10 MB) and allowed source types, but does not mention authentication, rate limits, or failure 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?

The definition is a single efficient sentence with the core constraint and accepted inputs front-loaded. There is no filler, though a brief distinction from send_file could have increased value without hurting 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?

For a straightforward send tool with full schema coverage and clear annotations, the description is largely complete. It covers accepted input sources and size limits; more detail on default chat behavior or failure modes is already handled by the schema.

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

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

Schema description coverage is 100%, so parameter semantics are already well documented in structured form. The description reinforces the photo parameter by restating accepted sources and adding a size limit not present in the schema, which is useful but modest.

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 clear verb and resource ('Send a photo') and states accepted input forms, making the purpose immediately understandable. It does not explicitly distinguish this tool from the sibling telegram_send_file, which likely handles generic files, so sibling differentiation is incomplete.

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 description of accepted photo sources, but there is no explicit guidance on when to use this tool versus telegram_send_message or telegram_send_file. The agent must infer the boundary from the tool name and description 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds a real operational prerequisite not present in structured fields — the bot must already be a member of the chat — which materially affects whether the call will succeed. It omits whether a reaction replaces a prior one or rate limits, keeping it from 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 leads and the precondition follows. 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?

No output schema exists, but annotations plus the full-coverage schema plus the membership precondition give an agent enough to call correctly. Minor gaps remain around failure modes and whether reactions overwrite, which a single clause could close.

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 all three parameters are already documented, which sets the baseline at 3. The emoji examples add flavor but don't constrain the allowed emoji set, and the description adds nothing for chat_id/message_id 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: 'Set an emoji reaction on a message.' This clearly distinguishes it from the send_message/send_photo/send_file siblings, which create messages rather than react to existing ones. It stops short of naming siblings explicitly, but the distinction is obvious.

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 emoji examples (👀 working, ✅ done, ❌ failed) imply a progress-reporting use case and the membership precondition is stated, but there is no explicit when-to-use vs. when-not guidance nor a pointer to any alternative tool. Usage is implied rather than directed.

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