Create Rear_port

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

Annotations already indicate write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it creates a new row and mentions dry-run consideration, which is helpful. However, it does not clarify if the operation is idempotent (annotations say false) or what happens on duplicate name. No contradiction with annotations.

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 very concise with three short sentences and a return line. It front-loads the core purpose. The second sentence ('This adds a new row') is somewhat redundant but not harmful. Overall, it earns its space efficiently.

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 complexity (11 parameters, no output schema), the description provides minimal context beyond creation. It mentions return formats but lacks explanation of the rear port's role in NetBox, relationship to front ports, or required parent object (device). The dry-run instruction is good, but more context would help the agent use the tool 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 73%, so many parameters are already explained (e.g., name, type, device_id). The description adds no additional parameter-specific meaning beyond the schema. The 'Returns' line mentions output formats, which implicitly relates to the response_format parameter, but is not tied to parameter semantics directly. Baseline score of 3 is appropriate.

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 'Create a new rear_port in NetBox', using a specific verb and resource. It explicitly mentions adding a new row, making the action unambiguous. The tool name and title reinforce this, and while sibling tools include other creation tools, the description's specificity to rear ports avoids confusion.

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 instructs to 'Ask before calling if the user wanted a dry-run', which provides a clear usage guideline for cautious execution. However, it does not differentiate this tool from alternatives like netbox_create_front_port or netbox_update_rear_port, nor does it specify prerequisites (e.g., device must exist). The guideline is useful but incomplete.

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