manage_hierarchical_labels

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

No annotations are provided, so the description carries the full burden. It implies mutation via 'add, remove' but never states whether removal is destructive or reversible, whether it cascades to connected pins, or what permissions are required. It does note the return shape ('Dictionary with label data or error'), which is a small plus, but the behavioral profile of a mutation tool is largely undisclosed.

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 front-loaded with purpose and then structured into Args/Returns sections. The two explanatory sentences about hierarchical labels earn their place by clarifying the concept, and there is little redundancy.

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?

An output schema exists, so return values need not be re-explained, and parameter documentation is thorough. However, for a mutation tool with zero annotation coverage, the description omits side-effect and safety context, leaving the agent under-informed about the consequences of the remove action.

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 must compensate — and it does, documenting all seven parameters including which are required for which action (text/position for 'add', label_uuid for 'remove'), the shape enum values, the size default, and rotation/size units. It adds real meaning beyond the bare schema.

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 clear verb (manage, with add/remove) and resource (hierarchical labels), and goes further by explaining what hierarchical labels do — connect child schematics to parent sheet pins for signal routing. It does not explicitly distinguish itself from close siblings like manage_labels, manage_global_labels, or add_label, so it falls short of a 5.

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 only usage guidance is the action list ('add', 'remove'). There is no statement of when to use hierarchical labels versus manage_labels or manage_global_labels, no prerequisites, and no exclusions. The agent must infer selection from the resource name alone.

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