remove_material

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

With no annotations, the description carries the full burden, yet it only states the top-level operations. It fails to disclose that deleting a datablock can affect other objects still using that material, that the delete action is destructive/irreversible, or what happens when object is null (the unassign branch likely becomes a no-op).

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?

One short sentence with zero filler. It front-loads the core action and communicates both modes compactly.

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 3-parameter mutation with no annotations and no output schema, the description is too thin. It omits the interaction between object=null and delete_datablock=false, lacks side-effect warnings, and does not state prerequisites (e.g., that the material must exist). Schema defaults help, but the description does not tie the pieces together.

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 descriptions cover object and delete_datablock, but material—the only required parameter—has no schema description. The tool description adds some context by mapping unassign to object slots and delete to the datablock, but it does not fully compensate for the unspecified material 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 names a specific verb+resource: 'Unassign a material from an object, or delete the material datablock.' It clearly distinguishes the tool from siblings like assign_material, get_material, and list_materials by stating both operations a material can undergo.

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—use this when you want to unassign or delete a material—but provides no explicit when/when-not guidance and does not mention alternatives such as assign_material. It also does not explain when an agent should set delete_datablock to true versus simply unassigning.

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