fork_delete

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

Annotations (destructiveHint: true, readOnlyHint: false) already flag this as a mutating operation. The description adds significant nuance beyond annotations by specifying exactly what is mutated and how: 'fork record is kept,' 'entries are tallied as archived,' and the reason is recorded. The explicit disambiguation 'it does not erase' directly manages agent expectations about destructive operations. The 'Irreversible' warning reinforces the annotation without contradicting it.

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, 51 words total. The description is extremely tight: it names the action, clarifies the lifecycle semantics, and adds a warning — all without a single filler word. The most critical behavioral caveat ('it does not erase') is parenthesized and emphasized without being buried. This is exactly the kind of front-loaded, information-dense structure that helps an agent parse quickly.

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, irreversible op, the description covers the core context well: what it does, what persists, and what happens to related dataset entries. It misses a few edge-case details an agent might need, such as: what happens if the fork is already closed? What if there are no entries to archive? And it doesn't mention error cases or idempotency. Still, given the guidance provided and the lack of an output schema requirement, it covers the main decision points for an agent.

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%, so the description is the only place to clarify parameter semantics. The description does explain that `reason` 'records why' the fork was abandoned — a meaningful semantic that explains its purpose. However, it provides no additional info on app_id or fork_id beyond their names, and there is no note on how to obtain or validate these identifiers (e.g., via fork_list or fork_status). The meaning is partially inferable from context, which earns a baseline 3.

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 leads with a specific verb and resource: 'Close an open fork as DELETED'. It clearly separates this from a hard delete by noting 'this closes, it does not erase' and gives the operational context ('the work was abandoned'), distinguishing it from sibling tools like fork_merge. The first clause alone disambiguates the entire purpose.

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 tells you when to use it: when 'the work was abandoned,' and what to expect as a side effect: 'its atom/kb change-log entries are tallied as archived.' It mentions fork_merge but only to draw an analogy about irreversibility, not to give explicit routing guidance (e.g., 'use fork_merge if you want to keep changes'). The context is clear, but it stops short of explicitly contrasting scenarios with sibling tools.

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