set_type

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

No annotations are provided, so the description must disclose behavioral traits. It states the mutation ('set') but omits details such as whether the type must be compatible with the element, whether existing references are updated, or if the operation is reversible. For a write operation, this is a minimal disclosure that leaves significant uncertainty.

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, focused sentence with no filler. It front-loads the core action and immediately specifies the target class. Every word contributes to the meaning, making it highly efficient.

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?

While the tool is simple (2 params) and an output schema exists (reducing the need to explain return values), the description lacks any mention of prerequisites, constraints, or relationships with sibling tools. It does not state that the element must be a TypedElement or that the type must be valid in the model context, leaving an agent without enough information to call it safely and correctly.

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 explain the two parameters. It implies that 'type_id' is the new type and 'feature_id' is the element being modified, but it does not explicitly state this mapping. The description adds only a vague hint; an agent must infer the roles from the parameter names, which are not self-explanatory beyond their titles.

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 uses a specific verb ('Set') and resource ('type of a TypedElement') and gives concrete examples (Property, Parameter, Port). This clearly distinguishes it from sibling setters like set_flow_direction or set_aggregation, which target different attributes. An agent can immediately infer the tool's function without ambiguity.

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 conditions like 'use set_value_type_unit for unit assignment' or any prerequisite checks. With many sibling setter tools, this lack of routing guidance forces the agent to rely on name matching alone.

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