suggest_orientation

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

With no annotations, the description carries the burden and does so: 'Changes nothing' declares read-only, it states the return shape (a ranked table with Rot(x, y, z) plus how), discloses that remote-server files are a temporary working copy deleted when unused, and forbids ssh/scp. Missing: cost or runtime expectations beyond the throwaway 'in a second' remark, and any note on accuracy limits of the 'rough estimates'.

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?

Front-loaded with the purpose, but the body is a run-on, telegraphic enumeration with parentheses and semicolons that reads like compressed notes rather than prose. Remote-server operational guidance is appended to a scoring description where it is only loosely related, costing the reader parse time for the value delivered.

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 7-parameter, no-annotation, no-output-schema tool, the description covers return shape, safety profile and remote file handling well, but leaves three parameters undefined and never clarifies the relationship between name, piece and variant. An agent could call it, but not confidently for multi-piece or variant cases.

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 and only partly does: it explains load with concrete format examples ('X', 'along Y', 'XZ', '1,0,1'), piece's default ('one printable part (default: each)'), and image's side effect. The size, variant and inline parameters receive no mention anywhere, leaving three of seven undocumented.

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?

Opens with a concrete verb and resource: 'Rank the ways to put the part on the bed', and enumerates the candidate set (six axis-aligned orientations plus convex-hull faces). It separates itself from siblings by naming build(d), export and download_part, though the mid-sentence enumeration of scoring criteria makes the core purpose harder to extract than it should be.

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?

Gives an explicit workflow rule ('ALWAYS before export') and a conditional trigger for the structural option ('with a load or the structural style'), plus a stated no-op case (a part already flat on the bed). It does not say when to skip it in favour of siblings like check or compare, so it stops short of full routing guidance.

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