set_node_parameter

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

With no annotations at all, the description carries the full behavioral burden. It usefully discloses value encoding (vectors/colors as lists, enums by id, $outputsize as log2) and the non-obvious log2 scaling example, which is real added value. It says nothing about persistence (does the change save to the package or only mutate in memory?), required permissions, or failure modes for invalid parameter names — significant gaps for a mutation tool.

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?

Three short, front-loaded statements with no filler; the operation is stated first and the encoding caveats follow. It is terse to the point of under-specification rather than verbose, which is the right side to err on.

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 5-parameter mutation tool with zero annotations, no output schema, and 0% schema coverage, the description leaves too much unsaid: the optional graph/package scoping, whether the edit persists, and expected return/error behavior are all absent. An agent could call it, but not confidently predict its effect or recovery from failure.

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% across 5 parameters, so the description must compensate. It clarifies the trickiest parameter (value: list for vectors/colors, id for enums, log2 for $outputsize) but leaves graph, package, and node_id completely unexplained — notably whether graph/package scope the operation to a non-active graph. Partial compensation only.

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?

"Cambia un parametro del nodo" states a specific verb (cambia) and resource (parametro del nodo), which clearly separates it from the read-side sibling get_node_parameter. It does not name that sibling explicitly, but the mutation scope is unambiguous.

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 value-encoding rules but no when-to-use guidance: it never says whether the graph must be open first, whether to prefer expose_parameter or create_node, or what to do when a parameter is not settable. The only usage context is implicit (the write counterpart of get_node_parameter).

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