Delete property groups

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

Beyond the destructiveHint annotation, the description discloses the full consequence chain: deletion happens in one undo step, non-empty groups are refused unless deleteDefinitions is true, and then definitions plus all their element values are destroyed. It also states that built-in groups cannot be deleted. This is unusually rich context for a destructive 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?

Three tightly written sentences, front-loaded with the core action and then the critical caveats. Every sentence earns its place and no filler is present.

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 mutation tool with annotations covering safety hints and no output schema, the description supplies the essential behavioral details: undoability, refusal conditions, cascading deletions, and built-in protection. An agent has enough information to invoke it correctly without further context.

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 67%; the schema documents the deleteDefinitions and undoName parameters and gives an item-level description for groups. The description adds meaning for deleteDefinitions by explaining that element values are also deleted, but it does not elaborate on the groups parameter format or undoName. Baseline 3 is appropriate given the partial coverage and added nuance for one parameter.

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 opens with a specific verb and resource: 'Deletes user-defined property groups'. It also distinguishes user-defined from built-in groups and states the undo scope, so the agent knows exactly what operation is being performed without opening the schema.

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 implies the tool is for user-defined groups and gives a key prerequisite for non-empty groups (deleteDefinitions must be true), plus the exclusion that built-in groups cannot be deleted. However, it does not explicitly name alternative tools such as delete_property_definitions or modify_property_groups, nor does it state when to choose this tool over them.

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