prune_fields

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

The description discloses that removed IDs are returned for auditability and that the operation is reversible via add_field. It also explains that thresholds are strictly-less-than and that page_index limits to one page. However, it does not describe what happens when no criteria are provided (e.g., deletes nothing or everything), which is a behavioral gap.

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 concise (3 sentences), front-loaded with the purpose, and logically structured: purpose first, then parameter details, then return value and reversibility. Every sentence serves a clear purpose.

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?

Despite explaining parameters and return value, the description omits a critical detail: the behavior when no criteria are provided. Since all parameters are optional, an agent might invoke the tool with no arguments, potentially deleting all fields—a dangerous outcome. The description should clarify this edge case.

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?

With schema description coverage at 0%, the description fully compensates by explaining each parameter's semantics: field_type for exact match, confidence_below/width_below/height_below as strictly-less-than thresholds (width/height in % of page), page_index to limit to one page, and exclude_ids to keep fields. This adds critical meaning beyond the bare schema.

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 tool's purpose: 'Bulk-delete fields matching ALL given criteria.' It specifies a verb (delete) and resource (fields), and the phrase 'ALL given criteria' and example 'detection noise' distinguish it from siblings like remove_field (single) or remove_fields (possibly different criteria).

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 lacks explicit guidance on when to use this tool versus alternatives. It does not warn about potential dangers (e.g., deleting all fields if no criteria are provided) or specify prerequisites. The sibling tools include remove_field and remove_fields, but no comparison is made.

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