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

The description mentions that 'the server stores only bounded metadata and an attested outcome', which adds transparency about side effects and outcome attestation beyond what annotations provide. However, it doesn't explain the nature of the 'attested outcome' or what 'bounded metadata' entails, and it doesn't clarify what happens if the local agent is not connected. With annotations indicating non-readonly but idempotent, this moderate disclosure is adequate.

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 a single, concise sentence that conveys purpose and a key behavioral note. It is front-loaded with the action and efficiently includes the caveat about metadata. No wasted words.

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 tool has 6 parameters, including nested objects and required fields, the description is sparse. It does not explain the purpose of idempotencyKey, the details object, or how the outcome is returned (since there is no output schema). The description is insufficient for an agent to confidently invoke this tool correctly, especially how to handle the local agent connection or what success looks like.

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 help clarify parameters, but it does not. The description mentions 'node' but not the specific parameters like projectId, nodeId, idempotencyKey, or the optional details object. The schema provides patterns and maxLengths, but no semantic meaning. Since there are 6 parameters with no schema descriptions, the description does not compensate for the lack of coverage.

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 states a specific action ('request the connected local agent to open node in editor') and specifies the resource ('node'). It is distinguishable from siblings like 'open_dashboard_widget' or 'submit_node_instruction' because it explicitly mentions opening in an editor. However, it doesn't explicitly differentiate from other node-related tools beyond that.

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 implies that this tool is for requesting an editor open, which suggests a use case of opening a node for editing. It does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. However, the phrase 'connected local agent' hints at a scenario where a local agent is available, providing some context.

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