delete_record_by_id

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

The annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful context about validated GUIDs, concurrency conditions, dry-run preview behavior, and ETag handling, though it does not mention required permissions or whether deletion is irreversible.

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 compact sentences, front-loads the core delete action, and wastes no words while including key safety-relevant details.

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 destructive annotations and rich schema, the description provides enough context to invoke the tool correctly, including dry-run and concurrency behavior. It could be slightly more complete by mentioning permission requirements or dependency/cascade effects, but those are not strictly required here.

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 89%, so the schema already carries most parameter meaning. The description references GUID validation, dry_run, and ETag semantics, but it does not add much beyond the detailed schema descriptions for if_match, allow_unprotected_write, and alias parameters.

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 a specific verb and resource: it deletes a native record, with validated GUID and concurrency conditions. This distinguishes it from sibling update/upsert/get record tools without requiring schema inspection.

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?

It explains that dry_run identifies the target without deleting, which implies preview usage, but it does not explicitly state when to choose this tool over alternatives such as update_existing_record, upsert_record_by_key, or get_record_by_id.

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