design_synthesize_rules

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

With no annotations, the description carries the burden well: it discloses that it is 'Pure Python, no Altium' (no live-app side effects), that rules with missing inputs are 'skipped with a note, never guessed,' and that output values are INTEGER MILS. It doesn't state idempotency or repeat-call behavior, which keeps it from a 5.

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?

Purpose is front-loaded in sentence one, followed by flow context, args, and returns in a scannable structure. The Returns block restates what the existing output schema already covers, which is some redundancy, and the roadmap reference is decorative padding.

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 4-param tool with untyped nested objects and an output schema, the description supplies the missing parameter semantics, the upstream dependency (fab profile from design_load_fab_profile), and failure shape ({ok: false, reason}). What the FabProfile must contain is deferred to the sibling tool, which is reasonable but leaves a small gap.

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 0% and every parameter is opaque (nested objects with additionalProperties), yet the Args block defines all four, including the precedence rule between plan_json and net_class_map and the accepted sub-keys of `options` (stackup, class_current_a, delta_t_c, diff_pair_target_ohms as required for differential rules). This adds substantial meaning the schema cannot 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?

Opens with a specific verb+resource+input: 'Synthesize PCB design rules + stackup ops from a fab profile.' It also names the concrete outputs it produces (pcb_create_design_rule and pcb_modify_layer parameter dicts), which cleanly distinguishes it from those sibling tools that actually apply rules.

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?

Places the tool explicitly in a workflow ('Stage 8 of the autonomous flow'), states dispatch ordering ('dispatched verbatim after pcb_create_net_class creates classes'), and gives precedence between plan_json and net_class_map. It stops short of explicitly naming when NOT to use it versus calling pcb_create_design_rule directly, so not a 5.

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