add_code_connect_map

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

With no annotations, the description carries the full burden, and it does disclose one genuinely non-obvious behavioral trait: mapping a component inside a component set maps the entire set. It also discloses the cross-tool effect on get_design_context. However, it says nothing about whether an existing mapping is overwritten, whether the mapping persists across sessions, or what a successful call returns.

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 sentences, no filler, and the purpose plus downstream benefit are front-loaded before the input-scope caveat. Every clause earns its place.

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 mutation tool with no annotations and no output schema, the description covers purpose, target selection, and the set-wide side effect, but omits overwrite/conflict behavior on re-mapping and any indication of the response. It is adequate to make the call correctly but not fully sufficient to predict the result.

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 coverage is 100%, so the baseline is 3, and the description earns above baseline by explaining that nodeId may be an instance, a component, or a component set id and by clarifying the scope consequence of choosing a component inside a set. That scope semantics is behavior the schema's pattern-only nodeId description does not convey.

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?

States a specific verb+resource ('Map a design component to a code component') and immediately names the downstream effect on get_design_context, which cleanly separates it from the sibling get_code_connect_map (read) and remove_code_connect_map (delete). An agent can identify this as the write-side of the Code Connect mapping trio without opening any schema.

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 when this matters ('so get_design_context names the code component for every instance of it') and constrains which node types may be passed, but it never states when to prefer this over remove_code_connect_map/get_code_connect_map, nor any prerequisites or conditions under which it should not be called. Usage is inferable rather than stated.

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