pt_add_devices

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

Annotations only declare openWorldHint=false, so the description must carry the behavior load — and it does: auto-layout when x/y are omitted and the notable side effect that router/switch boot is skipped so they're immediately ready. It omits failure modes (duplicate names, invalid models) and whether a handle/id is returned for later use.

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?

Front-loaded with the action and the payload shape, then supporting detail. The inline model list is long but justified since the schema provides no enum; a pointer to pt_catalog alone would have been tighter.

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 single-parameter creation tool with no output schema and thin annotations, the description covers the payload, layout defaults, and the boot-skip side effect. Minor gaps: whether added devices are returned/identified, and error behavior on invalid model names.

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 coverage is 0% and items are declared with additionalProperties and no property docs, so the description is doing all the work — it documents the object shape ({name, model, x?, y?}), which fields are optional, the model string format, and the consequence of omitting x/y. Only the semantics of `name` (uniqueness?) are left unstated.

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?

Starts with a specific verb+resource ("Add devices") and immediately enumerates supported model strings, which makes it distinguishable from pt_update_device and pt_delete_devices. It doesn't explicitly name those siblings, but the create semantics are unambiguous.

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?

Points at pt_catalog as the lookup for valid models, which is useful routing. However, it never states when to use this versus pt_update_device or pt_build, nor any preconditions such as whether the simulation must be started first.

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