workplane_grid

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

With no annotations, the description carries the full burden of disclosure. It reveals the computation method (inner-surface detection, plane at floor-top + workplane_h, spacing formula), the return format (points with direction [0,0,1] plus methodology breakdown), file writing behavior (write_pts=None to skip), and edge cases (clip_to_footprint ignored when interior_extent supplied). This is thorough and transparent.

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?

Four dense sentences pack in a lot of information without fluff. The purpose is front-loaded, followed by method and parameter specifics. While not overly verbose, it could be slightly more structured with bullet points for easier scanning, but it is appropriately concise given the complexity.

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?

Given 15 parameters and 0% schema coverage, the description covers the most critical ones but leaves several undocumented (units, up_axis, wall_thickness, north_angle_deg, work_dir, max_spacing). An output schema exists, so return values are covered, and the methodology is well explained. However, the parameter coverage gap makes it only moderately complete.

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. It explains workplane_h, border_offset, write_pts, material_map, sidecar, clip_to_footprint, footprint_border, and interior_extent, but leaves units, up_axis, wall_thickness, north_angle_deg, work_dir, and max_spacing (beyond the formula) unexplained. It adds meaning for the core parameters but not all 15.

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: 'EN 12464-1 working-plane illuminance grid from an OBJ room.' This clearly defines the tool's purpose and distinguishes it from sibling tools like run_grid or run_image by its focus on a compliance grid for a specific standard.

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 gives clear context (EN 12464-1, working-plane) and prerequisites (material_map or sidecar required). It also explains parameter behaviors like clip_to_footprint and its interaction with interior_extent. However, it does not explicitly name alternatives or state when not to use it, though the purpose itself implies the usage.

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