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

Adds substantial behavior beyond the annotations: the link is single-use and expires in one hour, the password is entered by the owner on a Conecto page and never visible to the agent, read-only keys receive "[redacted]", the call is free, and Conecto's own inboxes never send cold email. These are security and lifecycle facts an agent could not infer from readOnlyHint/destructiveHint/idempotentHint alone.

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 what the tool returns and who acts on it, then mechanics, then constraints. Five sentences are dense with non-redundant facts, though the trailing notes on redaction and pricing feel appended rather than integrated.

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?

One optional parameter, no output schema, no nested objects. The description covers who acts, what happens on the page, link lifetime, how completion is signalled, and key-permission edge cases – nothing an agent needs 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 the baseline is 3. The description goes slightly further by explaining the consequence of the provider value: gmail/outlook use an app password with servers auto-filled, other requires the mailbox's SMTP and IMAP settings.

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: it produces a link for the owner to connect one of the business's own mailboxes used by outreach campaigns. It distinguishes itself from siblings by naming outreach_mailboxes for listing and by scoping to outreach-sending mailboxes only.

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?

Clear context for when to call it (owner needs to attach a sending mailbox) and it routes the agent to outreach.mailbox_connected/outreach_mailboxes afterwards. It never explicitly says when not to use it or names a competing alternative tool for a different connection path, so it stops 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.