io_create_mail

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

Goes well beyond the annotations: it discloses that the phase-1 call makes NO network call, returns a preview plus confirmToken, that only a repeat call with that token proceeds, and it warns against prompt-injection writes originating from tool-result text. This is exactly the kind of side-effect and safety context annotations cannot express, and it is consistent with readOnlyHint=false / destructiveHint=true.

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?

Purpose is front-loaded in the first clause, and every subsequent sentence carries distinct information about the confirmation protocol and injection risk. It is dense and slightly run-on, but there is no filler to cut.

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 mutation tool with no output schema, the description covers the confirmation lifecycle and safety posture adequately. Minor gap: it never states the practical effect of a successful write (where the mail item lands, whether it can be undone), leaving the agent to infer the mutation's consequences from annotations alone.

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 confirmToken already thoroughly documented in the schema, so the baseline is 3. The description corroborates the confirmToken semantics but adds no parameter-level detail (formats, defaults, constraints) beyond the schema.

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

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

States a specific verb and resource ("Log a new mail item (package or letter) received in iOffice"), with the "received" framing implicitly separating it from io_deliver_mail and io_return_mail. It does not name those siblings explicitly, so an agent must infer the routing rather than being told it.

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 clear operating context: a confirmation prompt is required first, and it spells out the two-step fallback when the client lacks elicitation. It stops short of stating when to choose this over the other mail siblings (deliver/return), so the alternative-selection guidance is implied rather than explicit.

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