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

Adds valuable behavioral context beyond annotations: the key is shown once, acts with the operator's authority, is scoped to the company, and the bot reads the role's brief every turn via get_my_role. It doesn't restate the destructiveHint, but the authority implications are disclosed.

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 somewhat long and includes tangential detail (e.g., enumerating what get_my_role returns) that could be trimmed without losing essential guidance. It is still front-loaded with the core action and well-paragraphed, so it remains scannable.

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 tool with 4 params, no output schema, and mutation/destructive annotations, the description covers operation, outcome, parameter sourcing, approval workflow, and routing. Minor gaps like explicit replacement semantics are handled in the host parameter schema, so the description is sufficiently complete.

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 adds extra meaning by instructing to resolve agent_id from get_team_roster and by giving host examples (Grok Bot, Claude, ChatGPT) that map directly to the host enum, helping the agent understand parameter provenance and values.

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 clearly states the action: attaching a bot to one role and retrieving a key. It distinguishes from sibling detach_agent_key by explicitly pointing to it as the stop action, and from other attach-like tools by specifying role attachment and the get_team_roster source for agent_id.

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?

Provides explicit when-to-use conditions ('Use when the operator wants their own bot to wear a role instead of FreedomOS running it for them'), concrete user phrasing examples ('attach my bot / my Grok / Claude to <role>'), and names the alternative for stopping (detach_agent_key). Also covers approval nuance with 'call it on the first clear ask'.

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