plasticity_inspect_surface_structure

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

Adds meaningful context beyond the readOnly annotations: explicitly states it does not change the document, and clarifies the crucial distinction that UV values are native parameters rather than millimeter distances. Does not cover error behavior or revision-mismatch handling, but the semantic UV note is high-value.

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?

Single dense sentence that is front-loaded with the read-only scope and then enumerates the returned structure. Slightly long and comma-heavy, but every clause conveys distinct technical content.

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 two required params, full readOnly annotations, and no output schema, the description covers the return payload well (surface type, trim status, UV bounds, degrees/spans/control-points/rationality). It omits explanation of 'revision' semantics and how to obtain valid face IDs, leaving a minor completeness 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%, so the description must compensate. It clarifies that 'faces' refers to selected current Solid or Sheet faces (bodyId+faceId), addressing the primary parameter's intent. The 'revision' parameter is not explained in the description, which is a gap for a required field.

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 (read), resource (B-Rep surface structure), and scope (selected Solid or Sheet faces). Clearly distinguished from siblings like measure_face_properties or inspect_curve_structure by naming the exact structural attributes returned.

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?

Implies usage (when you need native topological/surface data for selected faces) but never states when to use this versus measure_face_properties, analyze_surface_continuity, or inspect_curve_structure. No explicit exclusions or prerequisites beyond the implicit 'selected current' faces.

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