arango_remove

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

The annotations already declare 'destructiveHint: true', indicating this is a destructive operation. The description adds minimal value by confirming it's a removal action, but it does not disclose additional behavioral traits such as whether the removal is permanent, if it requires specific permissions, or what happens on failure (e.g., error handling). With annotations covering the destructive nature, a baseline score is appropriate, as the description provides some context but not rich behavioral details.

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 description is a single, direct sentence ('Remove a document from a collection') that efficiently conveys the core action without unnecessary words. It is front-loaded and wastes no space, making it easy for an agent to parse quickly and understand the tool's intent at a glance.

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 the tool's complexity (a destructive operation with 2 parameters), the annotations cover the destructive hint, but there is no output schema to explain return values. The description is minimal and does not address what the tool returns (e.g., success confirmation, error details) or other contextual aspects like rate limits or side effects. It is adequate as a basic description but lacks completeness for effective agent use without additional inference.

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?

The input schema has 100% description coverage, clearly documenting both parameters ('collection' and 'key') with their types and purposes. The description does not add any semantic details beyond what the schema provides, such as examples or constraints (e.g., format of the key). Since the schema does the heavy lifting, a baseline score of 3 is justified, as the description neither compensates nor enhances parameter understanding.

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 clearly states the action ('Remove') and the resource ('a document from a collection'), making the purpose immediately understandable. However, it does not differentiate this tool from its sibling 'arango_update' (which might also modify documents) or specify what type of removal occurs (e.g., permanent deletion vs. soft delete), leaving room for improvement in sibling distinction.

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 provides no guidance on when to use this tool versus alternatives like 'arango_update' for modifying documents or 'arango_query' for retrieving them. It lacks context about prerequisites (e.g., needing an existing document key) or exclusions, leaving the agent to infer usage from the tool name and parameters alone.

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