insync_get_message

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

Goes well beyond the destructiveHint=true annotation by naming the exact side effect (marks the message read in the portal), its external visibility (the practice can see it), its irreversibility, and the gating parameter. This is precisely the context annotations cannot convey.

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?

Four sentences, front-loaded with the capability, then the warning before the mechanics. Every sentence carries information the agent needs; nothing is padded.

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 supplies the return contents and, importantly, the degraded metadata-only response when the read gate is not satisfied. For a four-parameter tool with a destructive side effect, nothing an agent needs to act safely 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 coverage is 100%, so baseline is 3, but the description adds real semantic value for allow_mark_read: without it the tool returns metadata plus a note asking the agent to confirm with the user. It also clarifies that body comes back as plain text.

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 one secure message in full') and enumerates the returned fields (subject, sent date, plain-text body, attachment list). The singular 'one ... in full' implicitly and effectively distinguishes it from the list_messages sibling.

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 states the gating condition: an unread message is not opened unless allow_mark_read is true, and an already-read message opens freely. It does not name sibling alternatives (e.g. insync_list_messages, insync_list_attachments) for partial-metadata needs, so it stops short of full routing guidance.

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