email_invitation

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

No annotations are provided, so the description carries the full behavioral burden. It states nothing about side effects (does it send an actual email?), required permissions, idempotency, or rate limits. The POST endpoint implies a mutation, but the description doesn't disclose what it creates or what happens on success/failure.

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 bloated with a redundant keyword dump that repeats generic verbs (create, add, new, make, write) and the tool name. The meaningful information ('Create email', POST path) is buried in boilerplate. No useful structure.

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 mutation tool with no annotations, no output schema, and a nested required body at 0% schema coverage, the description is completely inadequate. An agent cannot determine what this tool actually does, what the token represents, or how it relates to invite tokens.

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 0% and there is 1 required parameter ('body') which itself contains required 'email' and 'token' subfields. The description provides no explanation of the body structure, the meaning of 'token' (is it an invite token? an auth token?), or the email format required.

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 says 'Create email' but the tool is named email_invitation and the path is /api/households/invitations/email. It's ambiguous whether this creates an email invitation for a household or sends an email. The keyword soup ('email, households invitations, create, add, new, make, write') restates the title rather than clarifying the operation.

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?

No guidance on when to use this tool. With siblings like create_invite_token and send_invitation, the description doesn't explain which to use or in what sequence. The keyword list provides no contextual routing.

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