addDevice

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly reveals that the tool mutates the workspace by adding a device and explicitly states the uniqueness constraint for deviceName. However, it does not describe what happens if a duplicate is submitted, whether the operation can fail, or what response is returned on success.

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?

Two sentences with no filler. The core action is stated first, and the meaningful usage caveat about uniqueness follows immediately. Every sentence adds necessary operational value.

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 simple four-parameter add operation, the description, schema, and uniqueness guidance cover most of what an agent needs. Minor gaps include lack of explicit failure semantics on duplicate names and no mention of return/result behavior, but these do not prevent correct usage.

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 input schema already covers all four parameters with descriptions at 100% coverage. The description adds meaningful guidance beyond the schema by telling the agent to call getNetwork first to verify deviceName availability, which directly informs correct parameter selection. This slightly exceeds the high-schema-coverage baseline.

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 states a clear action ('Add a network device') and a specific resource ('workspace'). The tool's purpose is immediately clear and it is naturally distinguishable from sibling tools like addModule, addLink, and removeDevice, which target different objects or operations.

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 gives a concrete usage instruction: call getNetwork first if unsure whether deviceName is already taken. This is good when-to-use guidance for avoiding a likely failure, though it does not explicitly describe when not to use this tool. Since the action is so specific, this is sufficient context.

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