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

With no annotations at all, the description carries the full load, and it does disclose real behavior: the call returns an image rendering, PDFs are paginated by a 1-based index, and all content (including text burned into the image) is untrusted data rather than instructions. It omits a few operational traits an agent might want, such as supported formats, size limits, or behavior on an out-of-range page.

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 core capability and its exclusion are front-loaded in the first two sentences, with parameter and safety notes trailing. The prompt-injection warning spans two sentences that could be tightened, but they carry genuine operational weight rather than 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-annotation, zero-schema-coverage tool the security and pagination context is good, and no output schema means return values needn't be explained. However, the undefined `id` parameter is a genuine gap for correct invocation, and there is no guidance on failure modes such as an invalid page number.

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

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

Schema description coverage is 0%, so the description must compensate, and it only partially does: it clarifies that filename is the original name and that page is 1-based (the schema only shows a default of 1). The required `id` parameter is never explained — whether it identifies the message, the thread, or the attachment itself is left ambiguous.

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 ("View an image attachment, or one page of a PDF, as an image") and immediately scopes it with "Only for photos, posters and scans without text." That scope restriction is what separates it from the sibling get_attachment_text, so an agent can pick between the two without opening a schema.

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

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

"Only for photos, posters and scans without text" is an explicit when-not rule, which is more than most definitions offer. It stops short of naming get_attachment_text as the alternative for text-bearing attachments, leaving the agent to infer the handoff.

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 load well: it discloses the return fields (total_chars, next_offset, absence of next_offset at the end) and adds an explicit prompt-injection warning that attachment text and metadata are untrusted data, not instructions. It omits permission requirements and failure behavior for missing/binary attachments.

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 and pagination, followed by the security caveat. No filler and every clause adds 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?

With no output schema, the description usefully explains return values and pagination termination, and it flags the trust boundary. The remaining gap is parameter-level detail (id/filename, units, defaults) for a tool with four undocumented parameters.

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

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

Schema description coverage is 0%, so the description must compensate; it does partially by implying offset/length pagination through 'slice' and next_offset. However, it never explains what id and filename denote, the defaults (8000, 0), or that length/offset are measured in characters, leaving half the parameters undocumented.

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 ('Read a slice of one attachment's text') and explicitly positions the tool relative to get_item for documents longer than that tool shows. An agent can distinguish it from get_attachment_image and get_item immediately.

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?

Names the alternative (get_item) and the condition that selects this tool (longer documents), plus implies pagination via next_offset. It does not state the negative case for time periods beyond pagination or clarify when to prefer get_attachment_image, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the burden and does substantial work: it explains the return composition, how max_chars affects body and attachments, that truncated text is marked, and that school-provided content is untrusted data rather than instructions. It does not explicitly state whether the call has side effects such as marking an item seen, nor does it describe error 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 description is front-loaded with the core operation and then adds only high-value details: truncation behavior and the untrusted-content warning. Every sentence earns its place without unnecessary repetition.

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

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

There is no output schema or annotation coverage, so the description needs to explain return structure and behavior. It does so by describing the header/body/attachment sequence, truncation marking, and security handling. It is still missing usage guidance and any side-effect or error details, which keeps it from being 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 0%, so the description must compensate. It gives meaningful semantics for max_chars, including that the limit is shared across body and attachments and that cut text is marked. The id parameter is not elaborated beyond 'one item', but its role is largely self-evident.

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

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

The description uses a specific verb and resource: get one item, and it clarifies that the result includes the header, body, and each attachment's text. It is clear but does not explicitly differentiate itself from siblings such as get_attachment_text or get_thread_context.

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

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

It describes what the tool returns but gives no guidance on when to use it versus alternatives like search, grep_item, get_attachment_text, or get_thread_context. The agent must infer selection from the output 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?

With no annotations, the description carries the full burden but does contribute real behavior: result ordering, per-message shortening, and an explicit trust boundary marking message content as data rather than instructions. It omits failure behavior (invalid id, n larger than the thread) and whether whole messages or snippets are returned when n is small.

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, both front-loaded and free of redundancy: semantics first, then the injection-safety warning. The first sentence is slightly elliptical in dropping its verb, but no sentence 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 simple read tool with no output schema and no annotations, the description covers the core semantics and the trust boundary, which is the highest-risk aspect. It falls short on the max_chars budget semantics and on what a caller receives at thread boundaries, leaving the agent to guess at call-time correctness.

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

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

Schema description coverage is 0% with three bare-titled parameters, so the description must compensate. It only gives meaning to 'n' (count of preceding messages); 'max_chars' is never explained (per message vs. total budget), and 'id' is left as an unnamed 'item' with no hint of its type or source.

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

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

The description names the exact resource (the n messages preceding an item in its thread) and adds distinguishing traits: ordering (oldest first) and truncation (each shortened). It is clearly distinct from siblings like get_item and list_threads, though the fragment lacks an explicit verb and opens as a noun phrase rather than 'returns/retrieves'.

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 is given, and no sibling is named. The agent must infer that this tool is for expanding context around a specific item rather than paging a whole thread (list_threads) or fetching a single message (get_item).

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 and does disclose real behavior: matching is case-insensitive and literal (not regex), and results are small context windows rather than full items. It also flags the untrusted-content boundary. It does not state what happens when matches exceed a cap or whether it errors on a missing id.

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

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

Front-loaded with the core action and matching semantics in one sentence, followed by the return shape and the prompt-injection warning. The safety sentence is boilerplate but load-bearing for an agent handling message content; nothing is redundant.

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 no annotations, so the description is the only spec. It covers purpose, matching rules, and the trust boundary well, but leaves the two tuning parameters and any failure behavior (invalid id, no matches) undocumented.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It only conveys that `pattern` is a literal phrase and `id` identifies one item; `max_matches` and `context_chars` are never mentioned despite directly controlling output size and window width.

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 scope: find a literal word or phrase within a single item, case-insensitive, returning context windows. The 'within one item' scoping implicitly separates it from the sibling `search` tool, though it never names that sibling 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 phrase 'within one item' implies this is the single-item counterpart to a broader search, and the required `id` parameter reinforces that, but the description never says when to prefer `search` or `get_item` instead. Usage 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 full burden and usefully discloses that text is omitted, attachment metadata is tagged for images/scans/unreadable files, and embedded content is untrusted data. It does not state whether listing unseen items changes their seen status, what permissions are required, or other side effects.

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

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

The description is front-loaded with the return shape and then covers ordering, paging, and a security caveat. It is dense but every sentence has a purpose, with no obvious 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?

There is no output schema, and the description does a reasonable job enumerating returned fields and warning about untrusted content. Still, it leaves out the meaning of 'limit,' whether the call has side effects on seen state, and how it relates to the many sibling tools.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'order' and 'offset' meaningfully, but it never mentions the 'limit' parameter or its default of 20.

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 states a specific verb and resource: it lists unseen items without their text and enumerates the metadata returned. It distinguishes itself implicitly from text-fetching siblings by emphasizing 'without their text,' but does not explicitly name alternatives such as get_item or 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?

It gives concrete paging guidance ('use offset to page') and ordering options ('oldest (default) or newest'). However, it does not say when to use this tool versus search, get_item, or list_threads, nor does it state exclusions.

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

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

With no annotations, the description does real work: it discloses result ordering, the default filter, the aggregate counts returned, and an untrusted-content safety notice about school-sourced text. It omits permission/auth requirements and any pagination or truncation behavior behind the limit.

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

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

Front-loaded with the core action and scope in one sentence, with the injection warning kept separate and short. Every sentence carries information, though the safety boilerplate is somewhat generic.

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 and no annotations exist, so the description must carry the burden; it covers ordering, default filtering, counts returned, and content-trust handling. Only pagination/limit semantics and any permission requirements remain unaddressed.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it partially does by explaining that the default is unseen-only, which maps loosely to only_pending (though the wording "unseen" vs. "pending" is not an exact match). The limit parameter is never mentioned at all.

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?

Uses a specific verb and resource ("List threads") plus the ordering ("most recent first") and returned summary fields ("item and unseen counts"). It doesn't differentiate itself from the similarly-named sibling list_pending, so an agent must infer which listing tool to reach for.

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

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

The clause "by default only threads with unseen items" implies the default scoping and hints that a broader listing exists, but no sibling tool (list_pending, search, get_thread_context) is named and no explicit when-to-use/when-not-to-use condition 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 it does disclose two important traits: a 1-100 id batch limit and all-or-nothing atomicity when an id is unknown. It omits idempotency/repeat-call behavior, what error surface an unknown id produces, and whether the removal from list_pending is reversible.

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

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

One sentence, front-loaded with the action and its effect, then the batching rationale and the failure semantic. No filler; each clause adds an operational fact.

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 mutation tool with no annotations and no output schema, the description covers action, effect on a sibling, batching limits, and failure mode. Only the return value and idempotency remain unstated, which is a minor gap at this complexity.

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

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

Schema coverage is 0% and the single parameter 'ids' is an untyped-in-prose array of strings, so the description must compensate — and it does, specifying that ids holds 1-100 item ids and that the call is atomic across them. It could go further on whether ids are item ids from list_pending/get_item specifically.

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 ('Mark items as handled') plus the observable effect ('so they leave list_pending'), which lets an agent distinguish it from list_pending without opening either schema. It stops short of naming any other sibling or contrasting with alternatives like prune.

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

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

Gives an explicit precondition ('after their facts are saved') and a use case ('a backlog can be marked in a few calls'), which is real when-to-use guidance. It does not state when not to use it, e.g. whether re-marking already-handled items is harmless or whether prune is preferred for old items.

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 well: it discloses exactly what is destroyed (files, not rows), the default-safe dry_run behavior, and the exclusion rule that unseen items are never touched. Gaps remain on irreversibility, required permissions, and what a dry_run listing returns, so it is strong but not complete.

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 with zero filler, front-loaded with 'Maintenance:' to set context and the destructive action before the caveats. Every clause (rows stay, dry_run default, unseen exclusion) adds distinct information.

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

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

For a two-parameter tool with no output schema and no annotations, the description covers purpose, both defaults, destructiveness scope, and the key exclusion rule. Missing only operational details such as reversibility and return contents of a dry run, which are minor for this complexity.

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

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

Schema coverage is 0%, so the description must compensate — and it does for both parameters: older_than_days is explained as a day threshold defaulting to the configured retention_days, and dry_run is explained as list-only mode defaulting to true. Only finer details (units, null behavior of older_than_days) are left implicit.

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 concrete verb and object — 'delete the files of seen items older than older_than_days' — and immediately scopes it with 'rows stay' and 'Unseen items are never pruned.' The bare name 'prune' is ambiguous, but the text resolves it fully. It does not explicitly name a sibling for contrast, though no sibling appears to overlap.

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 'Maintenance:' prefix implies this is a housekeeping tool and the dry_run default of true signals the safe entry mode. However, it never states when to choose this over siblings like mark_seen or status, nor does it say what to do after a dry run before a real delete. Usage is implied rather than prescribed.

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 at all, the description carries the full burden and does it well: it discloses case-insensitivity, in-word matching, newest-first ordering, one short snippet per hit, and that total_items signals truncation. It also adds a prompt-injection warning about untrusted school content, which is high-value behavioral context; only permission/seen-state behavior is left unexplained.

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

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

Front-loaded with the core action and matching rules, then result shape, then usage, then the safety note — a logical progression with little waste. The untrusted-content sentence is long but earns its place as a security instruction.

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

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

With no output schema and no annotations, the description still covers ordering, snippet shape, and the total_items truncation signal, which is what an agent needs to interpret results. The remaining gap is control-parameter behavior (limit/include_seen), which is the one thing an agent could get wrong when calling it.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains the required 'query' semantics (every word must match, case-insensitive, substring matching), but says nothing about 'limit' or 'include_seen' — the latter is especially ambiguous since default true gives no clue whether seen messages are filtered in or out.

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 ('Search all messages') plus the exact fields searched (subject, sender, body, attachment text), so the agent knows this is a full-mailbox text search. It does not explicitly contrast with siblings like grep_item or list_threads, so differentiation is inferred 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?

'Use it to answer questions about earlier messages' gives a clear positive use case and implicitly scopes it to recall-style queries. There are no exclusions or named alternatives (e.g., when to prefer grep_item or get_thread_context instead), so it falls short of a 5.

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 must carry the full behavioral burden. It describes return contents but does not explicitly state that this is a read-only diagnostic operation, nor does it mention permissions, side effects, or whether it might trigger a sync.

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 that opens with the core purpose (counts and health) and then lists the specific data points. It is dense but contains no filler, though the long parenthetical enumeration is slightly less readable than a short structured list.

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

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

With no output schema and no annotations, the description should explain both what is returned and how the tool behaves. It does a good job enumerating returned fields, but it leaves behavioral aspects such as read-only safety and whether the tool has side 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?

The tool has zero parameters, so there is no parameter semantics to explain. The description appropriately does not waste space on nonexistent inputs, and the schema is complete for a no-argument tool.

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 that this tool reports counts and health, listing the specific categories such as pending items, failures, last sync, running state, and settings. This distinguishes it from action-oriented siblings like sync or search, though it does not explicitly name an alternative tool.

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 only enumerates what the tool returns; it gives no guidance about when to use this tool versus list_pending, list_threads, or other siblings. There are no conditions, exclusions, or recommended contexts for invocation.

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 must carry the safety burden, and it does disclose the critical side effect: fetching marks conversations as read in Admentum, which is exactly the kind of non-obvious mutation an agent needs. It still omits how 'new' is determined (no cursor/since parameter exists) and any auth or rate-limit context.

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, with the primary action front-loaded and the side effect immediately following.

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

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

Covers action, source system, return value (counts), and side effect for a zero-param tool with no output schema. The one real gap is how 'new' is scoped without any cursor or since argument, leaving the agent unsure whether state is server-side or whether this is a full re-fetch.

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 are no parameter semantics to explain; baseline 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?

Specific verb+resource: fetch new messages and attachments from Admentum, plus what it returns (counts). It does not differentiate from plausible siblings like list_pending or list_threads, which an agent could easily confuse with 'fetch new messages'.

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 'Fetch new messages' for a sync operation, but there is no explicit statement of when to prefer this over list_pending, search, or mark_seen, and no exclusions or preconditions given.

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