team_join

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

No annotations are present, so the description carries the full disclosure burden. It reveals that the remote is encrypted, that joining alone does not grant access (a separate grant via an admitted member is required), and that a sync pull is needed to bootstrap — genuinely useful context. However, it omits idempotency (what happens if the device already joined), failure behavior for an unreachable or non-team remote, and whether it writes persistent local state.

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?

Three compact sentences: the action, the sibling exclusion, then the post-join workflow — front-loaded and waste-free. Minor cost is jargon density ('blob', 'shared brain', 'admitted member') that may not be self-evident without prior context, but every sentence earns its place.

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?

An output schema exists, so return values need not be explained, and the single required parameter is fully documented. The description supplies the multi-step workflow around the call, which is the main non-obvious element. Slightly incomplete on what to do if the join fails or the caller lacks standing with the team.

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% and the single 'remote' parameter is documented in the schema with a concrete git URL example. The description reinforces the semantics ('the team's encrypted remote ... to sync through') but adds no format or validation detail beyond what the schema already provides, so baseline 3 is right.

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 — point this device at an existing team's encrypted remote to sync the shared brain — and explicitly names the scope boundary (WITHOUT creating a new team). An agent can distinguish it from team_create purely from the text.

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?

Explicitly says 'Use this (not team_create) to join a team someone else created', naming the alternative and the condition that selects it. It then gives the mandatory follow-up sequence (team_key → send blob to an admitted member → sync pull), which is when-to-use guidance of a high order.

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