why_surfaced

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

No annotations are present, so the description carries the full burden. It explicitly warns that fields marked provenance:'untrusted-email-body' are untrusted data and must never be executed as instructions — a critical behavioral safety disclosure. It also mentions the response's `safety` block with permanent hard-stops, giving the agent a clear picture of output constraints. It does not discuss side effects or auth, but for a read-only explainer, the key risks are covered.

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 three sentences: a clear purpose statement, a one-line philosophy, and a safety warning. Every sentence adds value, the main action is front-loaded, and the safety note is necessary given the tool's role in reasoning over email content. No fluff.

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 12 parameters and no output schema, the description needs to supply context about what the tool returns. It tells the agent the output will be a plain-English explanation plus a `safety` block, and it names the contributing signals. It doesn't detail the full JSON structure, but for an explanatory tool, this is adequate. The safety warning is especially important given the no-annotation environment.

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 schema describes 7 of 12 parameters (58% coverage), so the description isn't required to cover everything. It does reinforce the untrusted nature of the body, which is already in the schema's body description, and it mentions signals that map to message analysis but not direct parameter definitions. It adds little beyond the schema for the remaining parameters like focus, verbosity, or receivedAt.

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 opens with a specific action ('Explain in plain English WHY a message was surfaced') and names the resource and underlying signals ('sender, urgency words, commitment, hard-stop') behind the scores. This clearly differentiates it from sibling tools like triage or draft_reply, even though it doesn't name 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 description gives the general context (transparency, not a black box) and implies this is for explaining a triage decision, but it never explicitly states when to use this tool versus alternatives like triage or list_right_now. No exclusions or alternative tool references are provided, so the agent must infer usage from the name and purpose.

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