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

With no annotations, the description carries the full behavioral burden and does so well: it discloses required capabilities, mutation semantics, sub-layer copying rules, refusal cases, and that mismatched machine blocks are skipped and reported. These are exactly the operational details an agent needs before invoking a write operation.

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 dense but not bloated, and the main action and capability requirement are front-loaded. Every sentence adds relevant selection, refusal, or behavior information without repetition.

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 complex mutation tool with no annotations and no output schema, the description covers the critical gaps: permissions, copy semantics, selection behavior, refusal conditions, and partial-skip reporting. An agent has enough information to decide whether to call it and how to interpret the main failure modes.

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 already 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining the alternative entry selection modes, case-insensitive material name matching, and how thickness disambiguates multiple matches.

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 states a specific verb and resource: it copies a material library entry onto a cut entry, including which parameters and sub-layer values are copied. This is clearly distinguishable from the getter siblings and from update_cut, which modifies a cut rather than importing library material.

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?

It gives concrete selection guidance: use entry_guid, or material name with optional thickness. It also lists refusal and skip conditions, which effectively defines when the tool will not apply material, but it does not explicitly name update_cut or another alternative for related operations.

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

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

With no annotations, the description carries the burden and does useful work: it states the returned configuration fields, emphasizes that the secret is never revealed, and clarifies that reachability is current. It does not explicitly state that the tool is read-only or whether authentication is required, but the informational verb and zero-parameter shape make the behavior clear.

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 compact and front-loaded: it first says what the tool shows, then lists the relevant configuration fields, and ends with a useful security note. Every clause contributes information about the returned content or safety boundary.

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?

There is no output schema, so the description must convey return content, and it does by naming product, host, port, pairing, capabilities, and LightBurn reachability. It stops short of describing response structure or freshness guarantees beyond "right now," but it is otherwise complete for a simple zero-parameter info tool.

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?

There are zero input parameters, so parameter semantics are not applicable in the usual sense. The empty schema is consistent with the description, and no parameter-level compensation is needed.

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 states a specific verb and resource: it "Shows how this server is configured" and enumerates the exact configuration fields returned. It is clear what the tool does, though it does not explicitly distinguish itself from sibling introspection tools such as get_status or get_state_snapshot.

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?

Usage is implied: an agent would call this when it needs server configuration, pairing state, capabilities, or current LightBurn reachability. However, there is no explicit when-to-use guidance and no named alternative such as get_status for broader state checks.

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

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

With no annotations, the description carries the full burden and does well: it discloses the required capability, the drop-in-app restriction, the return content (PNG + metadata), and a key behavioral trait — it is a pure read of in-memory state with no new capture. It stops short of saying what happens when no overlay is drawn (null, empty image, or error), which is the main open question for a caller.

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 short sentences, each carrying distinct information, with the prerequisite front-loaded. The lead-off capability requirement slightly delays the statement of what the tool actually returns, but nothing is padded.

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?

There is no output schema, and the description compensates by naming the return payload (PNG image plus metadata). Combined with the capability gate and the no-recapture guarantee, an agent has enough to call this correctly; only the edge case of a missing overlay is undocumented.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No wasted effort explaining a nonexistent schema.

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: returns the camera overlay currently drawn on the workspace as a PNG image plus its metadata. This implicitly differentiates it from the sibling get_camera_overlay_metadata (metadata-only vs. image+metadata), though the distinction is left for the agent to infer rather than stated outright.

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 exclusion ("Returns what LightBurn already has in memory; it never triggers a new capture"), which tells the agent not to expect a fresh image, plus a prerequisite ("Requires capability 'project'") and environment restriction ("LightBurn only"). It does not name get_camera_overlay_metadata as the lighter-weight alternative, so routing between the two is only implied.

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

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

With no annotations, the description carries the burden well by disclosing the required capability, platform limitation, no-image-transfer behavior, and the 404 condition. It does not explicitly state read-only semantics or describe the exact response structure, but the behavior is largely clear.

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 very concise and every clause adds useful information. It is slightly telegraphic and leads with a prerequisite rather than the core purpose, but it remains efficient.

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 there is no output schema and no parameters, the description provides enough context to call the tool correctly: capability, platform scope, no image transfer, and error condition. It could be more complete by naming the returned fields' structure or explicitly contrasting with get_camera_overlay.

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 tool has zero parameters, so there is no parameter semantics to explain. The baseline score for a no-parameter tool applies.

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 clearly states the resource and returned metadata: camera overlay size, workspace placement in mm, and revision token. The phrase "without transferring the image" distinguishes it from the sibling get_camera_overlay 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?

It gives useful usage context: requires the "project" capability, is LightBurn-only, and returns 404 when no overlay is loaded. It implies when to use it instead of fetching the image, but does not explicitly name the sibling alternative.

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

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

No annotations are provided, so the description carries the behavioral burden. It usefully discloses the required capability and the return shape, including that a LightBurn normal cut has exactly one machine block via params.galvo or params.gantry. It does not spell out error behavior, but the key permission and payload context are present.

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?

Three short sentences with no wasted text. The capability requirement, retrieval behavior, and special params structure are each front-loaded and relevant.

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 simple one-index retrieval tool with no output schema, the description gives adequate context: permission requirement, index source, and notable return structure. 'Every field' is somewhat vague and error behavior is unstated, but the core needs are covered.

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 100%, and the sole parameter is documented as the flat index from get_cuts. The description repeats that same meaning but adds no extra syntax or edge-case guidance beyond the schema.

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 names a specific resource and scope: one cut entry, retrieved by flat index from get_cuts. It clearly distinguishes this tool from the list-oriented sibling get_cuts.

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?

It gives clear context by stating the index comes from get_cuts, and it notes the required 'project' capability. It does not explicitly compare against alternatives such as get_cuts or update_cut, but the usage context is clear.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the required 'project' capability, the fixed/known response shapes per backend, the meaning of 'index', and that values are in user display units. It stops short of stating that the call is read-only, the cost of the call, or what happens with an empty project.

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?

Information is front-loaded: the prerequisite capability comes first, then what is returned, then how to widen the field set. It is dense but every sentence adds usable context; the one weak spot is that the LightBurn layer-count enumeration is wordy relative to its value.

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?

There is no output schema, and the description compensates by describing the return structure, entry semantics, and field-level differences between compact and full mode. An agent can call this correctly and know how to consume the result without further lookup.

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 100%, so the parameters are already documented and the baseline is 3. The description's compact-mode note largely restates the schema, and it adds nothing about in_use_only, so it does not exceed the schema.

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 states the exact resource (the project's cut settings list) and what it contains, including the backend-specific structure (LightBurn's 30 cut layers / 2 tool layers / 1 internal entry / 30 image cuts vs. MillMage's operation list). It explicitly distinguishes itself from get_cut, update_cut, and get_units by naming each and their relationship.

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?

It routes the agent clearly: 'use compact=false or get_cut for every field' gives a concrete alternative with a condition. It does not cover when not to use this tool (e.g., when only a single known index is needed), and it never explains the effect of the defaulted in_use_only filter, so guidance is strong but not exhaustive.

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

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

No annotations are provided, so the description must carry the behavioral burden. It does disclose the capability requirement ('state'), which is real value, but says nothing about whether the values are cached/live, what happens if the machine is disconnected, or the return shape.

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?

Two short sentences with no waste. Minor structure issue: the capability prerequisite leads ahead of the actual purpose, so the agent reads a gate condition before learning what the tool does.

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 zero-parameter read-only getter with no output schema, the description covers purpose, unit context, and the access prerequisite. The only gap is the shape of the returned jog settings, which no output schema documents.

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?

Zero parameters, so the baseline is 4. The 'in display units' note adds useful semantics about the values returned, though it speaks to output rather than parameters.

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 resource and verb: it returns the current jog distance and speed settings, with the added qualifier 'in display units'. It's clear what the tool reads, though it doesn't distinguish itself from siblings like get_units or get_position that touch adjacent state.

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 'Requires capability "state"' clause gives an access precondition, which is useful, but there's no guidance on when to call this versus get_units, get_position, or get_state_snapshot. Usage is implied rather than directed.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the capability gate, the complete return field set, and the default filter ('by default only layers in use are returned'). It doesn't explicitly state that the operation is read-only with no side effects, which is the remaining gap.

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?

Three short sentences with no filler, and the capability gate is front-loaded. The field enumeration is dense but earns its place since there is no output schema.

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?

Because no output schema exists, the description must describe returns — and it does, listing all fields and the active layer index, plus the known count of 32. Only minor things like layer ordering or absence of side effects are missing.

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 100% and the single parameter already documents its default, so the schema does the heavy lifting. The description only corroborates the default and hints that disabling it yields all 32 layers; it adds little new meaning beyond the schema.

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 names the resource precisely (layer definitions plus the active layer index) and enumerates the exact fields returned, so an agent knows this is the layer-read tool rather than a position/units/settings getter. The verb is only implied by the tool name, but the resource is unambiguous among siblings.

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?

It states a prerequisite ('Requires capability "project"') and explains the default filtering, but gives no when-to-use guidance, no exclusions, and does not reference any alternative among the get_* siblings. Usage is only implied.

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

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 the required capability and the shape of returned data per application variant, but omits whether the call fails or returns empty without a project, whether it is read-only (only implied by 'get'/'currently loaded'), and any error behavior.

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?

Two short sentences with the prerequisite front-loaded and no filler. The second sentence is a sentence fragment ('The currently loaded material library…') that reads more like a title than a description, but it is information-dense rather than wasteful.

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?

No output schema exists, so the description reasonably compensates by enumerating expected fields for LightBurn and noting MillMage returns operation trees. For a zero-parameter getter this is nearly sufficient; only edge-case behavior (no project loaded, empty library) is missing.

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 tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. No misleading parameter text is present.

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 the resource precisely — the currently loaded material library — and goes further by explaining that the payload differs by host application (LightBurn flat entries vs. MillMage operation trees). The verb is only implied by the name, but the resource and contents are unambiguous and distinguishable from siblings like get_cuts.

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 prerequisite 'Requires capability "project"' is a real usage condition, telling the agent when the call is valid. However, there is no explicit when-to-use framing, no mention of what happens when no project is loaded, and no routing versus related tools such as get_cuts.

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

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

With no annotations, the description carries the full behavioral burden and does useful work: it discloses the required capability, guarantees mm units, and warns that unreported axes are omitted. It does not describe the return structure or ordering, but the key output semantics are covered.

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?

Three short sentences with no waste. The prerequisite is front-loaded, followed by what the tool returns and the unit/omission caveats.

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 zero-parameter read getter with no output schema, the description covers the essential context: capability gate, units, and missing-axis behavior. It could go further by mentioning the shape of returned coordinates or connection prerequisites, but it is largely sufficient.

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 tool has zero parameters, so there is nothing parameter-level to explain and the baseline is 4. The description correctly avoids discussing nonexistent inputs.

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 states a specific resource and scope: current machine and workpiece coordinates, always in mm. This clearly distinguishes a live position read from saved positions, though it does not explicitly name the sibling `get_saved_positions`.

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?

It supplies a prerequisite (`Requires capability "state"`) but gives no explicit guidance on when to choose this over siblings like `get_saved_positions` or `get_state_snapshot`. Usage is implied by 'current' coordinates rather than stated.

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

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

With no annotations, the description must carry behavioral context. It discloses the required capability and the returned fields, but does not explicitly state that the operation is read-only, what happens if no project is open, or any error behavior.

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 a single dense but purposeful sentence, front-loaded with the capability requirement and then enumerating return fields. It could be split slightly for readability, but it contains no filler.

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?

Because there is no output schema, the description usefully enumerates the returned metadata fields, including device and laser controller details. It is largely complete for a no-argument getter, though it omits edge cases such as no open project.

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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty schema is consistent with the tool taking no arguments.

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 names a specific verb/resource combination ("Metadata of the open project") and enumerates exactly which fields are returned. This makes it easy to distinguish from narrower getters like get_units, though it does not explicitly call out sibling alternatives.

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?

It states a prerequisite ("Requires capability 'project'"), but it does not say when to use this tool versus siblings such as get_state_snapshot or get_units. The use case is strongly implied by the enumerated project metadata, but explicit selection guidance is absent.

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

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

With no annotations at all, the description carries the full behavioral burden, and it does supply one genuinely useful fact: the required 'state' capability, which signals an auth/permission constraint. It says nothing about what a saved position contains, whether the result is a list, or what happens when none exist, so the disclosure is partial.

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?

Two short clauses, no filler, and the capability requirement is front-loaded so a caller learns the gate before anything else. The second clause is a fragment but still reads cleanly.

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 parameterless read tool this is close to sufficient, but with no annotations and no output schema, the description is the only source of behavioral detail and it omits the return shape (list vs object) and per-item fields. Minor gaps, but they are the only remaining source of truth.

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 tool takes zero parameters, so the baseline is 4; there are no arguments whose meaning the description needs to disambiguate. Nothing in the description conflicts with the empty schema.

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 names the resource precisely (saved positions) and its source (the device profile), which is more informative than a bare restatement of the name. It does not, however, distinguish this from the sibling get_position, leaving the agent to infer that one returns a single/current position while this returns a stored collection.

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 guidance is the precondition 'Requires capability "state"', which is a gate, not a usage rule. There is no statement of when to prefer this over get_position or get_state_snapshot, and no when-not guidance.

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

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

No annotations are provided, so the description carries the burden and does add useful behavioral context: capability requirement, aggregated scope, and the Ruida controller limitation that job.state is always idle and progress is never reported. It does not explicitly state read-only/no-side-effect behavior, but the 'get' naming and snapshot framing make the read intent clear.

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 compact and front-loads the capability requirement, then lists the snapshot contents, then gives the important controller caveat. Every sentence adds distinct information with no waste.

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 zero-parameter read tool with no output schema, the description sufficiently identifies what the snapshot contains and calls out a major controller-specific limitation. Exact return structure is not specified, but the field list and caveat are enough for correct tool selection and invocation.

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 tool has zero parameters, so there is no parameter semantics to explain; baseline for zero params is 4. The schema is empty and fully described by that absence.

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 a specific verb/resource combination ('Latest state snapshot') and explicitly enumerates the aggregated contents: position, job state/progress, overrides, aux state, connection and jog settings. The phrase 'in one call' distinguishes it from sibling getters such as get_position, get_jog_settings, connection_info, and get_status.

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?

It clearly frames the tool as a consolidated snapshot use case and states the prerequisite ('Requires capability "state"'). It does not explicitly say when not to use it or name alternatives, but the one-call aggregation context gives sufficient usage guidance.

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

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

With no annotations, the description carries the full burden; it does disclose a capability precondition and lists the shape of the response, which is real added context. However, it never says what happens when the capability is absent (error vs. degraded result), nor confirms this is a read-only, side-effect-free call.

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?

Two short sentences, with the capability precondition front-loaded before the payload description. The second sentence is a fragment and the bare field names (supports_z, supports_overrides) are undefined, but nothing is wasted.

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 zero-parameter getter with no output schema, naming the returned fields is exactly the right compensation. The remaining gap is the unexplained meaning of supports_z and supports_overrides, which an agent must infer.

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 tool takes no parameters, so per the baseline this lands at 4. The listed parenthetical fields are return values rather than inputs, so they do not mislead about parameter semantics.

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 resource: connection status and device capabilities of the selected device profile, and enumerates the returned fields (device_name, connected, supports_z, supports_overrides). It does not differentiate itself from the similarly named siblings connection_info and get_state_snapshot, so an agent must guess which one to pick.

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?

'Requires capability "state"' gives a useful prerequisite, but there is no guidance on when to use this versus connection_info or get_state_snapshot, which appear to overlap heavily. Usage is only implied by the tool's name and sibling set.

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

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

With no annotations, the description carries the disclosure burden and does add meaningful context: it states the required capability and explains output semantics, including that speed and distance units are independent. It still omits explicit read-only/idempotency language and error behavior, but for a simple getter the key behavioral context is present.

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?

Two sentences, front-loaded with the prerequisite and then the resource semantics. Every sentence adds useful information with no repetition or waste.

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 zero-parameter getter with no output schema, the description explains the relevant return fields, their allowed values, their independence, and the capability requirement. An agent has enough information to call and interpret it correctly.

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 tool has zero parameters, so the baseline score is 4. The description does not need to explain input parameters, and it appropriately focuses on output semantics instead.

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 clearly identifies the resource as the user's display units and specifies the output fields `units` and `distance_units` with their possible values. It does not differentiate this tool from sibling tools such as `get_status` or `get_jog_settings`, so it stops short of a 5.

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?

It provides a prerequisite (requires capability "state") and implies the tool is used to retrieve display-unit preferences, but it gives no explicit when-to-use guidance or alternatives versus sibling getters.

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

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

With no annotations, the description carries the full burden and does it well: it discloses the required capabilities (upload, plus state for confirmation), the destructive replacement of the current project, that LightBurn prompts to save unsaved changes, and that confirmation is only reliable for native formats otherwise reported as opened_unconfirmed.

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-loads the most important fact (capabilities and replacement behavior) in the first two sentences. The final sentence is long but each clause carries real information; only minor tightening is possible.

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 destructive, zero-required-parameter tool with no annotations and no output schema, the description covers prerequisites, side effects, timing behavior, and the possible success/opened_unconfirmed outcomes. Nothing essential for a correct call is missing.

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 100%, so the baseline is 3, but the description adds value by explaining the trade-off between path and content/content_base64 with a filename, and that the filename extension selects the importer. It reinforces rather than duplicates the schema wording.

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 effect ('REPLACES the current project with the file, like File > Open'), which precisely separates it from the sibling upload_file that merely uploads. The File > Open analogy makes the semantic outcome unmistakable.

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 concrete routing rules: send a local file via path, or content/content_base64 with a filename. It implies the difference from upload_file via the capability and replacement semantics, but never explicitly tells the agent when to use upload_file instead.

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

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

No annotations exist, so the description carries the full burden, and it does substantial work: it discloses the out-of-band consent dialog, the 30-second approval deadline, that the secret is persisted to per-user config and never returned, and that capabilities are immutable for the pairing's lifetime. Gaps remain around failure/timeout behavior, what happens if a pairing already exists with different capabilities, and what a successful response contains.

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?

Five short sentences, front-loaded with the action, then the consent/timeout mechanics, then the persistence and immutability constraints. Nothing is redundant and each sentence contributes an operational fact.

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?

With no annotations and no output schema, the description must carry everything, and it covers the interactive approval flow, credential handling, and capability lifecycle well. It leaves a modest gap on what the tool returns on success and how errors or a declined/timed-out consent are surfaced to the agent.

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 100% and the schema already enumerates all four capabilities and explains the camera-overlay inclusion under 'project', so the description's note about 'project' largely restates the schema. The added value is the lifetime-immutability constraint, which argues for deciding all capabilities up front, but that is framed behaviorally rather than as parameter guidance.

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: it pairs this server with a running LightBurn/MillMage instance on the local machine. This is an unmistakably different operation from every sibling (all of which are get_*/update_*/upload_* data operations), so an agent can position it without opening any schema.

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 clear operational context for when this runs (a consent dialog appears, the user must approve within 30 seconds) and an explicit re-invocation rule: 'call pair again to change them' since capabilities are fixed for the life of the pairing. It stops short of an explicit statement that pairing is a prerequisite for the get_*/upload_* siblings, and lists no when-not conditions.

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

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

With no annotations supplied, the description carries the full burden and does so: atomic validation ('LightBurn validates the whole body first and changes nothing on error'), undo behavior ('one undo step'), the review requirement before running, unit semantics ('display units (see get_units)'), and cross-field coherence rules like override_frequency and matching galvo/gantry profile. This is richer than typical annotation coverage.

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 capability requirement and the core contract before the long field enumeration. The middle sentence is a dense ~90-word wall, but nearly all of it is load-bearing constraint information rather than filler.

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 no annotations and no output schema, the description covers prerequisites, atomicity, side effects, units, and per-type validation rules. The only real gap is that it never states what the call returns (the updated cut entry?), which an agent may want to know when chaining calls.

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 100%, but the schema only says `changes` is a 'Partial cut entry'; the description enumerates which fields are actually editable per cut type (LightBurn normal, image, MillMage), the allowed mode values, the power range 0-100, and the override_frequency coupling. This adds substantial meaning the schema does not provide.

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: 'Partial update of one cut entry (LightBurn layer or MillMage operation) by its flat index from get_cuts.' It explicitly ties the index to the sibling get_cuts, so an agent can distinguish it from read-side siblings like get_cut/get_cuts and from apply_material_to_cut.

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?

Explains the prerequisite ('Requires capability "project_write"'), where the index comes from ('from get_cuts'), and the semantics of a partial update ('Only the fields in `changes` are modified'). It does not explicitly say when to prefer apply_material_to_cut over this tool, but the operational context is clear.

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

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

With no annotations, the description carries the burden well: it discloses capability requirements ('upload', plus 'state' for import confirmation), that the operation merges rather than replaces, that it blocks up to wait_seconds on LightBurn's file_imported event, and that it reports the outcome. It does not say what happens on timeout or import failure, which is the main remaining gap for an unannotated tool.

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?

A single dense paragraph with the capability prerequisite front-loaded and no filler sentences. The format enumeration is long but functional; the sentence about waiting/reporting could have been merged less verbosely, keeping it a point shy of ideal.

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 9-parameter, zero-required mutation tool with no output schema and no annotations, the description covers prerequisites, placement semantics, payload modes, and outcome reporting. The only missing piece is failure/timeout behavior, which matters here given the blocking wait.

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 already 100%, so the baseline is 3; the description justifies a bump by explaining the interaction between parameters — x/y as a pair with mm workspace semantics, origin selecting which bounding-box point sits at the anchor with center as default, and the three mutually exclusive payload channels. It still defers to the schema for group_shapes and filename details.

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 ('Imports a file into the CURRENT project (merge), like File > Import') and enumerates supported formats, so the agent knows exactly what happens. It implicitly distinguishes itself from open_file by emphasizing that the target is the current project and that it merges rather than replaces, but it never names that alternative.

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 clear conditions: current-project import, choose path vs content vs content_base64 depending on whether the file is local or generated, and x/y only when anchoring is desired (otherwise current view center). It lacks an explicit 'use open_file instead when you want to load a project file' exclusion.

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