Mailyond

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

With no annotations, the description carries the full burden and delivers real behavioral context: reading does not mark anything as read, and spam: true conversations cannot be replied to and can only be unmarked by a person in the dashboard. It omits auth requirements, rate limits, and pagination behavior, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with what the tool returns, then how to source the id, then the side-effect and spam caveats. Every sentence adds distinct value 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 single-param read tool with no output schema, the description covers return format (plain text, full message history), the id source, and the relevant side effects and spam constraint. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter's schema text already says 'The conversation id from list_conversations.' The description restates rather than extends that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read a full conversation') with explicit scope ('every message in it, oldest context included') and return format ('as plain text'). An agent can distinguish this from list_conversations without opening either 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?

Tells the agent where the required id comes from ('Pass the id from list_conversations'), which implicitly routes it to the sibling list tool first. It also gives concrete follow-up guidance about spam conversations, but does not state explicit when-not conditions.

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 deliver useful behavior: return granularity ('one entry per conversation with its latest message'), default ordering, and the default inbox filtering that hides spam and sent-only threads. It omits auth/permission requirements and pagination behavior, but the essentials for predicting results are present.

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 sentences, front-loaded with the core operation, then usage, then scope caveats. Every sentence adds distinct information with no redundancy or 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 six-parameter list tool with no output schema, the description explains the return shape and the default filtering behavior that most affects results. Remaining details (source flag semantics, paging nuance) live in the schema, so coverage is adequate though not exhaustive.

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

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

Schema description coverage is 100%, with defaults, enums, and formats already documented per parameter. The description adds little beyond the schema here -- its 'all domains' and folder-default remarks restate what the schema fields already say -- so the 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?

States a specific verb and resource ('List email conversations'), plus account-wide scope and a default sort ('newest first'). An agent can distinguish this list operation from get_conversation (single conversation) and the send/reply siblings without opening any schema.

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

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

Gives concrete usage contexts -- 'find replies and other mail that came in, or mail that has not been answered' -- and clarifies the default folder scope plus what is excluded (spam, sent-only) unless requested. It does not name the sibling tools or state when to prefer them, so it stops short of full when/when-not routing.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that results are scoped to the API key's read/send permissions and include verification status, which is genuinely useful, but says nothing about ordering, pagination, empty-result behavior, or that it is a non-mutating read.

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, no filler. The capability statement comes first and the sequencing advice second, so the reader gets the 'what' before the 'when'.

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 listing tool with no output schema, the description covers purpose, scope, returned fields, and invocation ordering. It could say a bit more about result shape (e.g. whether an empty list is possible), but nothing essential to calling it correctly is missing.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. No parameter-level explanation is 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 (List) and resource (domains), plus the scope ('this API key can read and send on') and the returned content ('verification status'). This distinguishes it cleanly from the conversation/email siblings, which operate on messages rather than domains.

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?

Explicitly prescribes sequencing: 'Call this first when you need a domain name for another tool.' That tells the agent when to reach for it and positions it as a prerequisite step, though it does not name which sibling consumes the domain or describe when not to call it.

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 the sender identity ('from address is the connected domain the conversation is already on'), automatic threading-header behavior, and a human-confirmation prerequisite before irreversible sends. It does not cover failure modes or rate limits, but the core behavioral traits are present.

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 the core action, then the identity/threading behavior, then the safety rule. No filler and each sentence carries 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 4-parameter write tool with no annotations and no output schema, the description covers identity, threading, recipient defaults, and the confirmation requirement. Return/error behavior is unaddressed, but the agent has enough to call it correctly.

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 id, to, cc, and text. The description's note that leaving 'to' empty replies to the inbound author largely restates the schema's stated default, and it adds nothing for cc or text. 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 ('Reply inside an existing conversation'), which implicitly separates it from send_email (a new message) and get_conversation (a read). It never names those siblings explicitly, so the differentiation is inferable 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?

Gives a concrete conditional instruction ('Leave "to" empty to reply to whoever wrote in') and a usage policy ('Ask the user before sending anything they have not seen'). It never says when to use this versus send_email, so an exclusion or alternative is missing.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the identity constraint (from must be on a connected domain), the thread-integrity side effect of the alternative path, and a required user-confirmation gate. It does not state whether sending is immediate/irreversible, what happens if the domain is unverified, or any rate limit, leaving some gaps for a mutation 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?

Three sentences, each doing distinct work: purpose, discovery path, alternative path plus consent rule. The core purpose is front-loaded and there is 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 send/mutation tool with no annotations and no output schema, the description covers the key decision points (valid senders, when to reply instead, user confirmation). It stops short of describing failure modes or delivery semantics, which is the main remaining gap given the absence of an 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 coverage is 83%, so the schema already documents the parameters and the baseline is 3. The description adds only the constraint that 'from' must be an address on a connected domain and points at list_domains for discovery — useful but largely duplicative of the schema's own 'An address on a connected domain' note.

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 new email') plus the scope constraint ('from one of your connected domains'). It explicitly differentiates itself from the sibling reply_to_conversation, so an agent can route correctly without opening any 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?

Names both alternatives and the conditions that select them: list_domains to discover valid from addresses, reply_to_conversation when the thread already exists. It also states a consent precondition ('Ask the user before sending anything they have not seen'), which is exactly the kind of when-to-use guidance that prevents misuse.

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