remove_entity

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'PERMANENT deletion', 'Irreversible', and details the dependency on parent_id per entity type. It also discloses verification status, which is uncommon and highly informative. It fully communicates the destructive and irreversible nature of the operation.

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 compact and front-loaded: first sentence states the purpose and irreversibility, second sentence gives the alternative, third provides parameter details, and a final line on verification status. Every sentence adds value, no fluff, and it's easy to scan.

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 destructive operation with no annotations or output schema, the description covers purpose, irreversibility, parameter requirements, and verification reliability. It does not mention return values, but that's not expected without an output schema. It provides enough context for an agent to safely decide whether to call it and how to construct the call.

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 0%, so the description must compensate. It explains parent_id for ad_group and keyword/ad, and lists allowed values for entity_type ('campaign | ad_group | keyword | ad'). However, it does not explicitly define what entity_id represents (though it's implied by name), and it doesn't clarify that parent_id is optional or null for campaign entities. Slight gap but mostly sufficient.

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 states a specific verb ('permanent deletion') and resource (campaign, ad_group, keyword, ad), and immediately differentiates itself from pause_entity by labeling the operation 'Irreversible' and recommending the alternative. This clearly distinguishes it from sibling tools like pause_entity and enable_entity.

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 explicitly says 'prefer pause_entity' as the safer alternative, and gives precise conditional requirements: 'ad_group needs parent_id=campaign id; keyword/ad need parent_id=ad group id.' It also flags verification status ('Live-verified... NOT live-verified...') to warn about reliability. This gives the agent clear when-to-use and when-not-to-use guidance.

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