pcb_validate_ddr_topology

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

With no annotations provided, the description carries the full burden of disclosing side effects and behavior. It does describe what the tool checks and that it validates against JEDEC limits, implying a non-destructive analysis, but it does not explicitly state whether the tool modifies state, requires additional context, or how it reports findings. This is partial transparency but not comprehensive.

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 two sentences, front-loaded with the primary purpose, and the second sentence enumerates specific validation checks without unnecessary filler. Every word adds value, and the structure allows quick comprehension.

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?

The tool has no output schema, so the description must explain what the user gets back. It details the checks performed but does not state the return format (e.g., pass/fail, violation list, report), nor any prerequisites beyond session_id. Given the complexity of DDR validation, this omission leaves the agent without crucial information about result interpretation.

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 100%, so the two parameters (session_id and ddr_standard) are already well-documented. The description adds a slight semantic hint that topology detection is 'auto' (suggesting ddr_standard might be auto-detected), but it does not elaborate on parameter usage or formats beyond what the schema provides. Baseline 3 is appropriate.

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 uses specific verbs ('auto-detect and validate') with a clear resource ('DDR memory interface topology') and lists concrete checks (byte-lane grouping, DQ-DQS skew, inter-byte-lane skew, addr/cmd-to-clock skew, fly-by topology) against JEDEC limits. It clearly distinguishes this from broader DDR analysis tools like pcb_analyze_ddr by focusing on topology validation from classified nets.

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 usage context by stating it works 'from classified nets' and requires a session_id, but it does not explicitly say when to use this tool versus alternatives such as pcb_analyze_ddr or pcb_analyze_ddr_timing_budget. There is no mention of when not to use it, leaving the agent to infer placement among siblings.

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