add_dtm

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

There are no annotations, so the description carries the full behavioral disclosure burden. It does communicate that the tool mutates the project topology and implies the added DTM is initially unconfigured until IP and dataset calls are made. However, it does not disclose duplicate behavior, whether the parent must already exist, persistence implications, or error conditions. The behavioral context is adequate but incomplete.

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 well-structured and every sentence earns its place: a clear one-line purpose, then two scenario definitions, then the necessary follow-up workflow. It is slightly longer than the minimal case but not redundant, and the most important information is front-loaded.

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 six-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is not complete enough. It covers the common top-level and slave workflows well, but it omits semantics for four parameters and gives no indication of the return value or error behavior. An agent would still have to guess about several inputs.

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 compensate. It explains parent_dtm and device_type_name well through concrete examples. But it leaves dtm_name, prog_id, version, and protocol_id completely unexplained, even though dtm_name is required. Four of six parameters remain underspecified, which is a significant gap for an agent trying to invoke the tool correctly.

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 opens with a clear verb and resource: 'Add a DTM to the project topology.' It also differentiates this from sibling hardware tools like add_io_module, add_drop, and add_rack by focusing specifically on DTM objects, and distinguishes top-level vs slave DTMs. An agent can tell what operation this performs and what object it operates on.

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 explicit usage guidance for the two main scenarios: leave parent_dtm empty for a top-level communication DTM, and set parent_dtm to the master's name for a slave device. It also names follow-up tools like set_dtm_address and get/set_dtm_dataset or set_dtm_control_parameters. It does not explicitly state when not to use this tool or compare it directly with alternatives, but the scenario-based guidance is strong.

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