score_placement

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

With no annotations, the description carries the behavioral transparency burden. It explicitly states that distances are in millimetres regardless of the document's Units attribute, which is a key behavioral detail. It also indicates non-mutation with 'without editing XML'. However, it does not disclose return value semantics (though output schema exists) or potential side effects, leaving some gaps.

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 short sentences. The first conveys the main purpose, and the second adds a critical unit caveat. There is no fluff, repetition, or unnecessary detail. It is well-structured and immediately front-loads the purpose.

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 5 parameters, no annotations, but an output schema. The description explains the core function and the unit caveat. However, it lacks parameter semantics, particularly for 'weights' and 'spacing', and does not position the tool relative to the many placement-related siblings. Given the output schema covers return values, this is a minimally acceptable completeness but with clear gaps.

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 schema description coverage is 0% for top-level parameters. The description only clarifies that all distances are in millimetres, which helps with x/y and possibly spacing/board_edge_clearance. It does not explain the meaning or usage of 'weights', 'path', 'spacing', or 'board_edge_clearance'. The nested schema provides structure for placements, but the description compensates poorly for the low schema coverage.

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 the specific verb 'score' and identifies the resource as 'an explicit component placement proposal'. The phrase 'without editing XML' clearly distinguishes this tool from editing tools like apply_component_placement_plan, making the purpose unambiguous.

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 provides clear context that this tool is for evaluating (scoring) a placement proposal without modifying files. It implicitly excludes editing use cases. While it does not name alternative tools, the 'without editing XML' clause offers a clear boundary. No explicit exclusions or alternatives are given, but the context is sufficient.

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