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

With no annotations, the description carries the behavioral burden. It does disclose useful behavior: the results are the latest messages, ordered oldest first, for either a channel or thread. It does not mention pagination semantics, output shape, or access requirements, leaving some transparency 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?

The description is a single, economical sentence with the key information front-loaded: resource scope, recency, and ordering. It is easy to parse and contains no filler, though it could carry slightly more detail without losing 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 flat four-parameter list tool, the description plus schema is minimally sufficient to make a call: channel_id is requiredainer and limit/before/after are explained. Since there is no output schema, the return shape is left implicit, and no auth, rate limits, or pagination behavior are mentioned. This is adequate but not complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds helpful framing around 'latest' and 'oldest first', which clarifies the meaning of before/after/limit, but it does not add significant parameter-level detail 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?

The description identifies a concrete resource ('channel or thread') and a clear result ('latest messages'), and even adds ordering ('oldest first'). It is distinct from siblings like dm_messages or channel_search, though it lacks an explicit verb like 'list' or 'fetch', so it is not a 5.

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

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

There is no explicit 'use this instead of X' guidance. However, 'latest messages in a channel or thread' implies this is the listing tool for recent messages, which differentiates it from channel_search and message_context. The usage context is inferable, but not spelled out.

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 of behavioral disclosure. It does add the useful ordering behavior ('newest first'), but it does not mention what a search returns, how pagination works, whether access restrictions apply, or any side effects. For a no-annotation tool, this is a significant transparency gap.

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

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

The description is a single focused sentence with no filler. The core scope is front-loaded, and the ordering behavior is stated efficiently. It is concise without being merely a tautology.

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?

Although the schema thoroughly documents parameters, the description offers no output format information, no usage context relative to sibling tools, and no behavioral details beyond ordering. For a 7-parameter tool with no annotations and no output schema, the definition is too thin to fully guide correct invocation.

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

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

Schema description coverage is 100%, and the description adds no parameter-specific meaning beyond that. The baseline of 3 applies because the schema already documents every parameter and its constraints.

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

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

The description states a specific verb ('Search') and resource ('one channel's or thread's messages'), and also conveys the sort order ('newest first'). It is clear about scope, but it does not explicitly differentiate itself from siblings like channel_messages or dm_search.

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 'one channel's or thread's messages' implies the tool is for scoped message search rather than guild-wide or DM search, but the description gives no explicit when-to-use guidance, exclusions, or named alternatives. Usage must be inferred from the wording and sibling names.

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. It usefully discloses the ordering (oldest first) and authentication requirement (user token), but it does not mention pagination behavior, return format, or whether the operation is read-only. This is adequate but not rich.

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 efficiently conveys the core purpose, ordering, and authentication requirement with no wasted words. The most important information is front-loaded.

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

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

Given the low complexity and full schema coverage, the description is mostly complete for an agent to invoke the tool correctly. It lacks an output schema, so return fields are not described, but for a simple message-listing tool the provided context is sufficient.

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 parameters are already well documented in the schema. The description adds no extra parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description identifies the resource (messages), scope (DM or group DM), and ordering (oldest first), which makes the tool's purpose clear. It distinguishes from guild-focused siblings like channel_messages by specifying DMs, though it lacks an explicit verb like 'gets' or 'lists'.

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 clearly states when to use it: to get the latest messages in a DM/group DM. It also adds the important prerequisite that a user token is needed. However, it does not explicitly mention alternatives or when not to use it, such as pointing to channel_messages for guild channels.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses a real constraint (requires the user token) and the sort order (newest first), which is meaningful context. However, it stays silent on pagination behavior, the shape of results, and any rate-limit implications of searching, which a token-sensitive tool could usefully mention.

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 single sentence is tight and front-loaded: purpose first, then scope (DM/group DM), then ordering, then auth. Nothing is wasted, though it is short enough that an explicit sibling pointer would be a justified addition rather than 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?

With 7 parameters, no output schema, and a sibling set containing dm_messages, list_dms, channel_search, and guild_search, the description covers the core (scope, ordering, auth) but leaves the search/dm_messages distinction implicit and says nothing about the return shape. For a search tool, this is adequate but not complete.

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

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

Schema description coverage is 100%, so every one of the 7 parameters is already documented with descriptions (has, after, limit, before, content, author_id, channel_id). The description adds only the token and ordering context, nothing parameter-specific, so the baseline 3 applies.

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

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

The description states a specific verb ('Search') and resource ('a DM or group DM') plus ordering ('newest first'). The 'DM' resource implicitly differentiates it from guild_search/channel_search siblings, but it does not name those alternatives explicitly the way a 5 would.

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?

'DM or group DM' implies the search scope and rules out guild/channel search, but the description never says 'for guild channels use guild_search' or contrasts with dm_messages. The auth note ('needs the user token') tells the agent when the tool might fail, but no direct when-to-use/when-not-to-use guidance is given.

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 disclose the key behavioral trait: the return form is conditional on the attachment type. However, 'as its metadata' is undefined, and there is no disclosure of error cases, response encoding, or what happens when the attachment is unavailable.

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 roughly 21 words with the key behavioral distinction (type-dependent return form) front-loaded before the alternate behaviors. Every clause maps to a distinct case, and there is no filler or redundancy.

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

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

For a single-parameter tool with no output schema, the description covers the typical invocation path: supply an attachment URL, get a type-appropriate representation. It is incomplete in that the 'anything else' fallback is vague, and error behavior is not hinted. Given the tool is simple and the sibling list provides no alternative attachment tool, the coverage is adequate but not polished.

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 schema already explains that the url is the attachment link from a message's `[attachment: ...]` marker. The tool description adds nothing about the parameter beyond what the schema provides, so the baseline score 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?

Describes the tool as returning an attachment's contents, and differentiates the return form by type (image as image, text as text, anything else as metadata). This clearly separates it from sibling tools, which center on guilds, channels, messages, and DMs. The only weakness is that the action verb 'fetch' appears only in the tool name.

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 explicit when-to-use or when-not-to-use guidance and never mentions alternatives or exclusions. The only contextual clue, that the URL comes from a message's `[attachment: ...]` marker, is provided in the schema parameter description rather than the tool 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does convey the core behavior: find the first matching server member and return their user id. But it omits no-match behavior, matching semantics like exact vs partial or case sensitivity, and how 'first' is ordered, and it never confirms the operation is read-only.

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

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

The description is a single compact sentence that leads with the returned value, then states the search criterion and intended use. No filler or redundant restatement of the tool name is present.

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 lookup, the description plus schema covers the input and the returned value well. However, there is no output schema or annotation, and important context such as no-match behavior, ordering, and authorization is missing, leaving the description adequate but not fully complete.

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

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

Schema description coverage is 100%, so the schema already explains `name` as username/nickname and `guild_id` as server id with a default-server fallback. The description adds the context that the match is the first server member and that the output feeds author_id searches, but it does not significantly extend parameter-level 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 clearly identifies the tool as returning the user id of the first server member matching `name`, and it connects the result to `author_id` searches. This is a specific lookup action distinct from sibling tools that search guilds, channels, or DMs, though it does not explicitly contrast 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?

The phrase 'for `author_id` searches' gives an implied use case, so an agent can infer when this tool is relevant. However, it does not state when not to use it or explicitly compare it to alternative sibling tools, leaving the guidance only implicit.

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

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

No annotations are provided, so the description carries the burden. It discloses the output format (one per line, with ids, types, parent categories, topics), which is useful. However, it doesn't mention whether this is a read-only operation, any rate limits, or what happens if the guild_id is invalid. The description adds some behavioral context but not comprehensive.

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 sentence that packs in the output format and key fields. It is concise and front-loaded with the main purpose. It could be slightly more structured, but it earns its place with 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 list tool with one optional parameter, the description is mostly complete. It tells the agent what the output looks like and what the parameter means. However, it doesn't clarify whether the output is plain text or JSON, and it doesn't mention any filtering or sorting options. Given the lack of annotations and output schema, a bit more context would help, but it's adequate for a simple tool.

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

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

Schema description coverage is 100% for the single parameter, so the schema already documents guild_id. The description adds context that the default server is used if omitted, which is already in the schema's default field. The description doesn't add much beyond the schema, but the schema is sufficient. Baseline 3 is appropriate.

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

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

The description states a specific verb ('The channels of a server') and resource (channels), and specifies the output format (one per line with ids, types, parent categories, topics). It is clear what the tool returns, though it doesn't explicitly name a sibling to distinguish from, so it loses a point.

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

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

The description implies usage: call this to list channels of a server. It doesn't explicitly say when to use this vs alternatives like guild_tree or channel_messages, but the context of sibling tools and the description's focus on channel listing makes the intended use reasonably clear. No exclusions or alternatives are mentioned.

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

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

No annotations are present, so the description carries the behavioral disclosure burden. It usefully reveals that the search spans all channels/threads and returns newest-first, but it doesn't mention permission requirements, default-server fallback, or what the result shape 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 description is a single sentence with the key facts front-loaded: action, resource, scope, and ordering. There is no filler or repetition of schema 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 an 8-parameter tool with no annotations and no output schema, the description is adequate but has gaps. It doesn't cover return format, permissions, or how to choose between guild_search and channel_search/dm_search, though the schema and scope statement cover the core invocation needs.

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

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

Schema coverage is 100%, with all 8 parameters individually documented including defaults, so the baseline is 3. The description adds one useful nuance—that omitting channel_id searches across all channels/threads—but otherwise relies on the schema for parameter 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 uses a specific verb ('search') and a clear resource ('a server's messages'), and further specifies scope ('across all channels and threads') and ordering ('newest first'). This distinguishes it from channel-scoped siblings like channel_search and channel_messages, and from dm_search by focusing on a server.

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 a clear usage context: server-wide message search. It doesn't explicitly name alternatives or state when not to use it, but the 'across all channels and threads' scope strongly implies when this tool is appropriate versus channel- or DM-scoped searches.

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 disclosure burden. It usefully states what the returned map contains, and 'map' implies a read-only retrieval, but it does not explicitly state read-only semantics, response shape, or caveats such as result size or member detail depth.

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 one compact sentence with no filler. It front-loads the core idea ('A map of a server') and then lists the included elements 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 tool with two optional parameters and no output schema, the description gives a high-level picture of the return contents. However, it omits output structure, usage guidance, and any performance or size caveats, leaving it minimally sufficient rather than fully complete.

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

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

Schema coverage is 100% and both parameters have descriptions in the schema, so the baseline is 3. The tool description does not add parameter-specific detail beyond clarifying the overall result content.

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 identifies the resource ('a server') and the returned content ('categories, channels with their ids and topics, and members'). It is clear about what the tool provides, but it is phrased as a noun phrase rather than an explicit action verb, and it does not differentiate itself from sibling tools like guild_channels or find_member.

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

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

The description implies the tool is for getting a structural overview of a server, but it provides no explicit when-to-use guidance, no exclusions, and no named alternatives. The intended use is inferable 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?

With no annotations, the description carries the disclosure burden. It discloses an auth prerequisite ('needs the user token') and a scoping detail (open DMs and group DMs only), but it does not characterize the response beyond channel IDs or mention ordering/pagination behavior beyond what the limit schema already covers.

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 resource, return value, and auth requirement with no filler or repetition. 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?

For a low-complexity tool with one optional parameter and no output schema, this is nearly complete: it tells the agent what will be returned and that a user token is required. It could specify the full response object shape, but the channel-ID detail is sufficient for downstream use with dm_messages.

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 only parameter, limit, is fully described in the schema (default 50, most recent activity first), so the description adds no extra meaning beyond clarifying that the returned DMs carry channel IDs. Baseline 3 applies because schema coverage is 100%.

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 clearly identifies the resource (the account's open DMs and group DMs) and the key output (channel IDs), which makes it distinct from list_guilds. It does not explicitly contrast itself with dm_messages or dm_search, so it stops short of full sibling differentiation.

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

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

The description implies this is the entry point for retrieving a user's DM channel IDs and notes the token requirement, but it does not state when to choose it over dm_messages/dm_search or mention exclusions. The context is usable but not explicitly prescriptive.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states only the data scope and that IDs are included, but does not disclose return shape, ordering, or whether all guild data is returned, leaving notable gaps for an unannotated 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?

The entire description is one compact phrase with no wasted words and the key idea appears first. It is appropriately sized for a zero-parameter tool, though a more explicit verb like 'Returns...' would make it marginally stronger.

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 zero-parameter listing tool, the description is minimally viable: it names the returned entity and a key field (IDs). However, without an output schema, it does not fully specify the return format, and the lack of any guidance relative to sibling guild tools leaves the context incomplete.

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

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

The tool has zero parameters, so no parameter documentation is needed in the description; there is no semantic burden to carry. The baseline for zero-parameter tools 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 clearly identifies the resource (joined servers and their IDs, which is the tool's scope. It is specific enough to identify list_guilds as a listing operation over guilds, though it lacks an explicit verb and does not contrast with the sibling guild_* tools.

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 minimal context ('servers the bot has joined') but provides no guidance on when to choose this over siblings like guild_search, guild_tree, or guild_channels. No exclusions or alternative conditions are mentioned.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It adds value beyond the schema by stating the oldest-first ordering and the contextual 'around one message' nature. However, it does not disclose whether the anchor message itself is included, how edge cases are handled, or that this is a read-only operation, leaving notable 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?

The description is a single eight-word sentence with zero fluff. It front-loads the core concept and every word contributes to meaning. This is an appropriately sized description for a simple retrieval 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?

The description is adequate for a simple read operation, and the schema covers all parameters fully. However, there is no output schema and no mention of the return shape, edge cases (e.g., insufficient messages before/after), or whether the anchor message is included. Given the absence of annotations, a bit more behavioral context would make this more complete.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description does not add meaning beyond the schema: 'around one message' loosely maps to message_id, but the schema already documents message_id and limit's centering behavior adequately. No additional parameter nuance is provided.

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 clearly identifies the resource (messages around a specific message) and the ordering behavior (oldest first), which distinguishes it from siblings like channel_messages or channel_search. However, it lacks an explicit verb such as 'Retrieve' or 'List', so it reads as a noun-phrase description rather than a full purpose statement.

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

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

No guidance is given on when to use this tool over channel_messages, channel_search, or other siblings. The description does not mention prerequisites, alternatives, or exclusions, so an agent must infer usage entirely from the name and brief phrasing.

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