set_particle_settings

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

With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It only says 'Set', implying a mutation, but does not state whether attributes are overwritten or appended, how extra_params is interpreted, whether a missing system_name defaults to the active system, or what happens if the object has no particle system. There is no mention of side effects, errors, or return behavior, leaving significant ambiguity for a write 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 a single, concise sentence that front-loads the action and includes illustrative examples. It avoids unnecessary verbosity and is efficiently structured for quick reading. The trailing '...' slightly undercuts completeness but does not significantly harm conciseness.

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 tool's complexity (3 parameters, no annotations) and the presence of an output schema (not shown), the description is underdeveloped. It fails to mention that the tool modifies an existing particle system, how extra_params interacts with the system, or any preconditions. An agent cannot confidently invoke this tool without additional assumptions about Blender's particle API. The description is insufficient for a complete, correct 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?

The schema has zero description coverage for its parameters, so the description must compensate. It does so by listing example attributes (count, lifetime, frame_start) that likely belong to the extra_params object, giving partial semantics. However, it does not explain the roles of object_name and system_name, nor explicitly state that extra_params is a dictionary of attribute-value pairs. The description adds some meaning beyond the bare schema but leaves gaps.

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 action ('Set particle settings attributes') and lists relevant examples (count, lifetime, frame_start), which convey the resource and scope. It is distinct from siblings like add_particle_system or list_particle_systems, though it does not explicitly contrast with them. The verb+resource is clear enough for an agent to identify the tool's basic purpose.

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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., that a particle system must already exist via add_particle_system), nor does it clarify whether it is suitable for creating or only modifying systems. There is no 'when to use' or 'when not to use' context, leaving the agent to infer from the name alone.

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