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

Discloses key behavioral traits beyond annotations: the agent keeps the same id, JD, activities, and run history, never mints a twin, and is archived specialists are absent from the active roster. The approval-tier note also explains real-world invocation behavior. The description is consistent with annotations' destructiveHint=true and readOnlyHint=false.

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 the core action and key constraint, with routing and approval details after. Some minor redundancy ('never mints a twin' / 'Never remint' / 'same id, JD, activities, and run history') is acceptable given the importance of not creating a duplicate.

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?

Given no output schema and the tool's mutation nature, the description covers what is needed to call it correctly: how to find the archived id, what not to call, the approval flow, and the fact that it operates on the existing row. Nothing essential 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 description coverage is 100%, and the schema already documents both agent_id and companyId. The description adds useful resolution guidance for agent_id but does not materially expand parameter semantics beyond what the schema provides, so it meets the baseline.

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 ('restore') and resource ('archived specialist') and clarifies the operation is in-place with is_active=true on the existing row. It explicitly distinguishes itself from hire_agent_with_context and set_company_lifecycle, so an agent can select it correctly among siblings.

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 trigger phrases, tells where to resolve agent_id (get_team_roster.archived or get_agent_outcome_panel), warns against hiring a new agent, and notes that company-unarchive is a different path. This leaves no ambiguity about when to call this tool versus alternatives.

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