set_knobs

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

The annotations already declare readOnlyHint=false, destructiveHint=false, and a closed-world (openWorldHint=false) surface, so safety traits are largely covered. The description adds one useful behavioral fact beyond them: it returns the post-write values, so the agent knows the response reflects the applied state; this was not obvious from the annotations. It stays silent on update semantics, such as whether supplied knobs are merged with existing values or partial updates replace settings, and how mode affects behavior.

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 short sentences with the action stated first, so no wording is wasted. The definition is terse to the point of under-specification, but that is penalized in other dimensions, not this one.

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?

The tool is moderately complex: it has four parameters, a required nested arbitrary-properties object, an enum mode, and an optional script. The description covers almost none of this. An output schema does exist, so the return values do not need explaining, but the description is still far too thin for a mutation tool with this much parameter surface.

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 should carry the burden of explaining meaning, but it only restates two of the four parameters in generic terms. It never explains the mode enum (auto/live/headless), the purpose of script, or the expected shape and value types of the nested knobs object.

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 uses a specific verb and resource: 'Set one or more knobs on a node.' An agent can immediately tell this is a write operation on node parameters, unlike sibling reads such as get_node or list_nodes. What it does not do is distinguish the tool from related mutators like set_selection, so the definition falls short of 5 on this dimension.

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?

It gives no guidance on when to use this tool rather than alternatives, never explains what conditions require a write versus a read, and says nothing about prerequisites. The only usage cue is implied by the verb 'Set,' which is not real guidance.

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