Get advanced device settings

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

Annotations already mark this tool as read-only and idempotent, so the safety profile is covered. The description adds meaningful behavioral details: values are in API units, port=0 selects the controller, and the same data appears in get_port_settings_raw on AI controllers. There is no contradiction with the 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 compact and front-loaded, opening with the core action and scope, then listing contents, units, and the raw-endpoint alternative. Every sentence earns its place without repetition or filler.

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 read-only annotations, the presence of an output schema, and the simple two-parameter input, the description covers everything an agent needs to call the tool correctly: what it returns, the special port=0 case, unit semantics, and the relationship to a sibling tool. No critical behavior is left unexplained.

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 schema only documents controller_id; port has only a title and numeric bounds. The description compensates by explaining that port=0 means the controller rather than a physical port, which is essential semantic information. It adds less for controller_id, but the schema already describes that parameter adequately.

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 names a specific verb and resource: it returns the advanced settings object (getDevSetting) for a port, or the controller when port=0. It also lists the contained fields, which makes the tool's purpose concrete and distinguishable from the raw/basic port-setting siblings.

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 clear context: it works on both controller families and notes that on AI controllers the same data is nested inside get_port_settings_raw, which helps route an agent to the raw variant when appropriate. It does not explicitly state when not to use this tool versus get_port_settings, but the distinction is mostly clear from the word 'advanced'.

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