proj_get_differences

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

With no annotations, the description carries the full burden. It usefully discloses that a project compile happens as a side effect, which matters for an agent sequencing other calls, but it never says whether the tool is read-only, whether compilation can alter or dirty project state, how long it takes, or whether license/UI state is required.

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 core definition is one front-loaded sentence, followed by a tight bullet list of the result categories and a short Args note. The trailing 'Returns' block partially restates the bullets, but it names the exact keys, so the small redundancy still 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 one-parameter read/comparison tool with an output schema present, the description is close to complete: purpose, categories of result, and the parameter fallback are all covered. The remaining gap is behavioral — no statement of read-only-ness or what the implicit compile does to the document.

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?

The single parameter has 0% schema coverage, so the description must compensate — and it does, explaining that project_path is optional and that omission falls back to the active project. That is precisely the semantics the schema lacks; it just doesn't state the path format or whether a relative path is accepted.

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 and resource — get differences between schematic and PCB netlist — and enumerates the three categories of result, so the agent knows exactly what comes back. However, it never distinguishes itself from close siblings like proj_compare_sch_pcb, proj_sync_pcb, and proj_sync_schematic, which a reader could easily confuse with this tool.

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 hint about when to use it is the mention that it 'compiles the project and uses component mappings'. There is no statement of when this is preferable to proj_compare_sch_pcb (comparison) or proj_sync_pcb/sync_schematic (remediation), nor any prerequisite or ordering guidance.

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