delete_agent

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

The description goes far beyond the annotations by disclosing the ON DELETE SET NULL foreign-key behavior, explaining that monitors survive with 'ping history and incidents completely intact,' keep running 'on its existing schedule, no longer attributed to any agent,' and remain visible via list_monitors/get_monitor. It also flags that the action 'cannot be undone.' This complements the destructiveHint=true and idempotentHint=true annotations without contradicting them — no annotation contradiction.

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?

Every sentence earns its place: the core action leads, followed by the critical side-effect warning, visibility consequences, the two alternative operations, and the irreversibility note. There is no filler or redundant restatement; the length is justified by the non-obvious cascade behavior that genuinely needs explanation.

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 destructive tool with no output schema, the description covers all decision-relevant context: what gets destroyed (the agent row only), what survives (monitors, ping history, incidents), what survivors look like afterward (unowned, still scheduled, still listed), and how to accomplish reattachment or full removal via update_monitor/delete_monitor. The only omitted details are edge cases like repeated-call behavior, but the idempotentHint annotation already communicates that expectation.

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%, with the id parameter already described as 'Agent UUID (from register_agent or list_agents),' so the schema carries the full semantic load. The description reinforces that the UUID targets the agent being permanently deleted, but adds no new format, source, or syntax details beyond what the schema already provides.

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 opens with a specific verb+resource+scope: 'Permanently delete a LastPing agent from the registry by UUID,' which unambiguously defines the action. It also distinguishes itself from the closely related sibling delete_monitor by explicitly stating 'deleting the agent alone never does that' when referring to removing monitors, so an agent can tell the two apart immediately.

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?

The description gives explicit alternative routing: 'To reattach a survivor, call update_monitor with agent_id set to a different agent's id or slug' and 'To also remove a monitor, call delete_monitor on it separately.' It also states a clear when-not condition — this tool never removes monitors — so an agent knows exactly when a sibling tool is required instead.

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