deregister_agent

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

With no annotations, the description carries the full behavioral burden, and it does disclose useful facts: messages are preserved for audit, the agent is marked inactive, and it can no longer send or receive messages. It omits reversibility (does unretire_agent restore a deregistered agent?), any auth requirements for the undocumented registration_token, and side effects on existing reservations or contacts.

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 sentences, front-loaded with the action and immediately followed by the concrete effects; every sentence earns its place. Slight deduction because the effect sentences could have been compressed into one without losing information.

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 no explanation, but the definition still leaves gaps: 0% parameter documentation, no annotations, and no differentiation from the retire/hard_delete siblings. For a destructive-adjacent lifecycle tool this is only minimally adequate.

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% across three parameters, so the description must compensate and largely does not. It implicitly maps to agent_name and project_key, but registration_token (optional, nullable, defaulting to null) is never explained, and no format or identifier conventions are given for any parameter.

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 states a specific verb and resource ('Remove an agent from a project') and clarifies the effect (marked inactive, dropped from the active roster). However, it never distinguishes itself from the very similar siblings retire_agent, unretire_agent, and hard_delete_agent, leaving the agent to guess which removal semantics apply.

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?

There is no when-to-use guidance and no mention of the obvious alternatives in the sibling set (retire_agent, hard_delete_agent). An agent cannot tell from this text whether deregister is soft, reversible, or terminal relative to those tools.

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