bulk_delete_records

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

With no annotations provided, the description carries the full burden. It discloses the destructive nature ('Delete'), the batch mechanism, a hard limit (1000 GUIDs), and per-record success/failure tracking with partial success. This adds meaningful behavioral context beyond the raw name and schema.

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 three concise sentences, each adding distinct value: the purpose, the API limit, and the partial success behavior. No fluff or repetition; it is fully front-loaded with the core action.

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 tool with no output schema, the description adequately covers the main aspects: operation, batch size, and per-record result handling. It implies the return format (per-record success/failure) but does not explicitly state the response structure, leaving a minor gap for a moderately complex operation.

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 schema already provides 100% coverage for both parameters (recordIds and tableName). The description adds context about the batch operation and partial success, which clarifies how recordIds is processed and what outcome to expect, enhancing the schema's basic descriptions.

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 it deletes multiple records in a single OData $batch operation, using a specific verb 'Delete' and defining the scope ('multiple records', 'single OData $batch operation'). This distinguishes it from siblings like delete_record (single) and bulk_create_records/bulk_update_records.

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 implies usage for bulk deletion when multiple records need to be removed efficiently, with explicit limits (1000 GUIDs per call) and partial success support. However, it does not explicitly state when NOT to use it or directly compare to alternatives like delete_record.

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