aoci_remove_entry

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

No annotations are provided, so the description carries the full behavioral burden and does so: it discloses exactly what is destroyed (only the misplaced/orphan Domain Entry), what is preserved (Root, Meta, object Volumes, saved Evidence, Baseline/Database Binding, and the existing expected owner), and the ownership-conflict special case. It also explains the dangling-annotation consequence - a model-authored artifact handled on the next Whole-Index read, not by the machine - which is non-obvious semantics an agent would otherwise get wrong.

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 critical constraint ('Use only for an explicit orphan Entry candidate') is correctly front-loaded, and nearly every sentence carries distinct information about guards, rejections, or preserved objects. However, the prose is dense and run-on, stacking internal vocabulary with little structural separation, which makes it harder to scan than a short flat statement of the rule would be. Information-rich but not efficiently structured.

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?

With no annotations, no output schema, and a single fully-described parameter, the description covers everything an agent needs: eligibility, the special ownership-conflict path, transaction guards, what is never removed, and the rejection states. Nothing material is missing for correct invocation.

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% and the single 'path' parameter is already documented as accepting a Legacy repository-relative path, code:<path>, or canonical database:// object_ref. The description restates the same three identities with a bit of added framing about which form applies to Legacy vs Volumes v1, but supplies no syntax detail, examples, or failure modes beyond the schema. Baseline 3 applies since the schema does the heavy lifting.

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 opening sentence states a specific verb and resource - remove an orphan Entry that governance has already flagged - and the body clarifies that it removes only the Domain Entry, never the source file, database object, Evidence, Root, Meta or Volume. It also names the sibling aoci_report for the non-orphan case. The purpose is clear, though the density of internal jargon (Legacy, Volumes v1, Whole-Index, Baseline Binding) makes it slower to parse than it needs to be.

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?

Explicit preconditions: 'Use only for an explicit orphan Entry candidate returned by governance', plus a stated exclusion ('Removing a non-orphan requires a maintainer decision recorded with aoci_report') and a strong anti-pattern warning ('never delete a workspace or database object merely to manufacture an orphan'). Also defines rejection conditions: recovery, changed, unproven, or third-party state is rejected. When-to-use, when-not, and the alternative are all present.

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