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

With no annotations, the description carries the full burden and does substantial work: per-op authorization levels, the side effect that invite pulls a new person into the org on accept, the send_email=false behavior returning a link instead of mailing, and the fact that set_instruction layers on top of the org guide. It stops short of stating reversibility of remove_member, idempotency, or error behavior for an unauthorized caller.

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?

Resource definition is front-loaded and the slash-delimited op map packs a large amount of routing information into minimal text with no filler. The dense run-on parentheticals are efficient but demand careful parsing, which slightly hurts scanability.

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 13-parameter, 8-op dispatcher with no annotations and no output schema, the description covers op selection, permission gates, parameter binding, one return-value sketch (get returns members and shared/lent accounts), and cross-tool boundaries. The only gaps are the three leftover top-level params and output shape, which are minor at this complexity.

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 0%, so the description must compensate, and it mostly does: it binds group_id, name, org_id, target (as sub or email), email, send_email, slug, body_md and role to specific ops, and supplies the enum values group_member|group_admin. It leaves _org, title and description entirely unexplained and gives no format detail for sub vs email in target.

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?

Opens with a concrete resource definition ("Teams (departments) of an org") and then enumerates eight specific verbs with their required parameters, so an agent knows exactly which operations exist. It also differentiates from the nearest sibling by pointing at oto_use_group for switching teams and at the dashboard for shared secrets.

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?

Every op carries its own when-to-use context and prerequisite: create requires org_id/name and org-admin, get requires membership or org admin, list_invites and add_member require team lead, add_member notes the target must already be in the org, and invite is explicitly for NEW people. It also names the alternative tool (oto_use_group) and an explicit exclusion (team shared secrets never via MCP).

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