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

Goes well beyond the annotations by disclosing the physical consequences (everything stops, heaters off), the irreversible-ish follow-up state (board must be restarted), and the approval/auth behavior (always available, never asks for approval). Note a mild tension with destructiveHint=false, since this aborts an in-progress job and forces a restart, but the description does not literally contradict the hint.

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, front-loaded with what the tool does, followed by the consequence and the availability/approval caveat. Every sentence earns its place with 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?

For a parameterless emergency action with no output schema, the description supplies everything an agent needs: the trigger semantics, the effect, the recovery requirement, and the fact that it is always permitted. Nothing material 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, which is the baseline-4 case; the description correctly signals a no-argument action. No parameter semantics are needed or omitted.

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 action (emergency stop), maps it to the underlying G-code (M112), and enumerates the concrete effect: stops everything at once and switches heaters off. This is unmistakably distinct from the read-only status siblings like get_status, job_status, and get_sensors.

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: always available, never requires approval, and requires a board restart afterwards (power cycle or M999 with approval). It doesn't explicitly contrast itself with a graceful 'cancel job' alternative, but it does describe the recovery path and approval semantics, which is strong guidance for a last-resort action.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the current configuration state and the env vars required to make the call succeed. However, it says nothing about what the call returns (image bytes, base64, URL, or a content block) or how it fails, which is a meaningful gap for an image 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?

Two sentences with zero filler: the purpose and scope lead, and the blocking prerequisite follows immediately. Every clause earns its place.

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 should carry more about the return value, and the lone parameter is undocumented. The config-state warning is genuinely useful, but a complete definition would also route the agent to list_local_cameras to discover a valid camera value.

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 single 'camera' parameter has 0% schema description coverage, so the description must compensate. It implies cameras are named/configured via DUET_CAMERAS but never states what values the parameter accepts (name vs. index vs. URL) or what happens when it is omitted.

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 ('Fetch a still image from a configured camera') plus the intended purpose ('to inspect the print or workspace'). It does not name or differentiate itself from the sibling list_local_cameras, which is the obvious adjacent tool, 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?

Gives a clear context of use (visual inspection of a print or workspace) and an actionable prerequisite: cameras are currently unconfigured and DUET_CAMERAS/DUET_CAMERA_URL must be set. It stops short of 5 because it never points to an alternative such as list_local_cameras for discovering valid camera names.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds a genuinely useful behavioral fact beyond that: the call does not move any axis, so endstops can be safely triggered by hand during the read. It does not describe the response payload, but with a safety profile already provided by annotations this is minor.

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 tight sentences, zero filler. The core behavior is front-loaded and the usage note follows immediately after.

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 sensor read with no output schema, the description covers what is returned (triggered-or-not per axis), what does not happen (no motion), and the intended diagnostic workflow. Nothing material 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 there is nothing to disambiguate; the baseline for a parameterless tool is 4. The description correctly implies no arguments are needed ('per axis' results come back generically).

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 ('get_endstops' → current endstop states per axis) and immediately scopes it with the qualifier 'without moving anything'. An agent can distinguish this from get_sensors/get_status because it is explicitly about endstop trigger states, not general sensor readings.

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 usage context: check wiring by pressing each endstop by hand before homing. This tells the agent exactly when the tool is useful, though it names no alternative tools and states no explicit when-not-to-use condition.

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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds real behavioral context: the result includes a verification verdict expressed as tested / expected / unsupported, warning the agent that the server may be in a partially unsupported state. It does not mention freshness, caching, or failure modes.

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 tight sentences, front-loaded with the payload and closed with the operative usage cue. No filler, no restatement of the name.

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 output schema, the description carries the return-value burden and does list the key fields plus the verification enum values. It is sufficient for a simple no-arg probe, though it does not say whether verification status can change over time.

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. The description's field listing is return-value information rather than 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?

The description names the concrete resource and its payload fields: board, firmware version, verification status, and uptime. This is clearly distinguishable from generic siblings like get_status, though it never explicitly contrasts itself with get_machine_profile, which sounds adjacent.

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?

"Use it first to know what you are talking to" gives an explicit call-order recommendation, which is strong context. It stops short of naming alternatives or when-not-to-use cases.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety profile and non-network nature are covered. The description usefully adds that values originate from config.g settings rather than live machine state, but is silent on the meaning/effect of the refresh parameter and on caching.

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 tight sentences with zero filler; the safety framing and the when-to-use directive are front-loaded and immediately actionable.

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, but the description compensates by naming the categories of returned settings, and it makes clear when the data is needed. Only the refresh parameter's semantics remain unexplained.

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% and the sole parameter 'refresh' is never mentioned in the description. The name is fairly self-explanatory, but the description does not explain whether refresh forces a re-parse of config.g, what the default is, or the cost of refreshing.

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 (parsed/read) and resource (safety-relevant machine settings from config.g) and even enumerates the fields returned (axis limits, heater max temps, motor currents). It does not explicitly contrast itself with the nearby get_machine_info, so it stops short of 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?

Explicitly prescribes the moment to call it: 'Read this before planning any motion or heating.' That is a clear usage context, but no alternative sibling is named for cases where the agent wants live state rather than config-derived values.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description merely restates 'Read-only' — no credit earned there. It adds almost nothing else: no note on whether values are live vs. cached, what happens when a sensor type is absent, or dynamic keys in the response. Given no output schema exists, the description leaves the return behavior largely undisclosed.

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, no filler, and the sensor inventory is front-loaded. It loses a point only because the trailing 'Read-only' duplicates the annotation rather than adding information.

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 no-parameter read tool this is close to sufficient, but with no output schema the description should convey the shape of the returned sensor data (grouped by sensor type? firmware-reported names?) and clarify the boundary with get_endstops. Those gaps leave an agent guessing about the payload.

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 rubric the baseline is 4. Nothing in the description is needed to explain parameter usage, and it introduces no misleading parameter hints.

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 set (probes such as BLTouch, filament monitors, analog temperature sensors, endstops) so an agent knows what category of data comes back. It is a noun phrase rather than a verb+resource, and it does not differentiate itself from the sibling get_endstops, which the description itself lists as in-scope — a real ambiguity for tool selection.

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?

There is no when-to-use guidance, no statement of when to prefer get_endstops, get_status or get_machine_info instead, and no prerequisites. The only directive-like content is 'Read-only', which is a property, not 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful content about what state is surfaced, but nothing about polling frequency, staleness, or cost of calling it repeatedly for a live-updating snapshot.

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, zero padding. The content inventory comes first and the sibling-routing instruction is placed last, which is the right front-loading for a status reader.

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 output schema, the description's field enumeration does the job of telling the agent what it will receive, and it defers events/supervisor/speed to job_status. The one soft spot is the word 'compact', which hints at a fuller variant without saying what was omitted or where to get it.

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, which is the baseline-4 case. There is no parameter semantics to clarify, and the description correctly spends no words on argument handling.

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 ('machine state') and enumerates its contents precisely: status, heaters with current/target, axes with position/homed/limits, and the current job with file/layer/progress. It also explicitly distinguishes itself from the sibling job_status, so an agent can tell the two apart without opening schemas.

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 an explicit routing rule: 'For events, supervisor and speed use job_status.' That is a clear when-to-use-elsewhere signal. It does not, however, address other closely related siblings such as get_machine_info or get_sensors, so the differentiation is partial rather than complete.

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?

Annotations already establish readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe read. The description usefully adds that the response covers supervisor activity and event types (pauses, warnings, connection problems), which is real context, but it says nothing about freshness, polling cost, or how the events window behaves.

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 efficient sentence with the highest-value content (machine status, progress, supervisor state) front-loaded and no filler. The trailing list is dense but each item earns its place as a returned field.

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 output schema, the description does a reasonable job enumerating what comes back, but it omits the one parameter's meaning and any routing guidance. For a monitoring tool with 11 siblings it is adequate but leaves clear gaps an agent would need to resolve by trial.

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% and the single 'events' parameter (integer, default 10, max 50) is never mentioned as a parameter. 'its most recent events' hints that events are returned but does not connect to the adjustable count, its default, or its 0-50 bound, so the description fails to compensate for the coverage gap.

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 enumerates the specific data the tool surfaces (machine status, file, layer, progress, heater targets, supervisor state and events), which tells an agent exactly what kind of result to expect. It lacks an explicit verb and does nothing to distinguish it from the overlapping sibling get_status, keeping it below 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?

There is no when-to-use, when-not-to-use, or alternative guidance. With get_status and get_machine_info in the sibling set, an agent has no signal for choosing this composite overview over those narrower calls; usage must be inferred entirely from the field list.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds only the fact that the target is the SD-card filesystem; it says nothing about whether results are recursive, sorted, truncated, or how many entries come back.

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?

One short, front-loaded sentence with no filler; the examples earn their place by documenting the path format. Nothing is redundant with the annotations or schema, though the single sentence leaves no room for routing guidance.

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 one-parameter read-only listing tool with no output schema, the description covers the essentials (what it lists, where, example paths). It is still incomplete on return shape — file names only vs metadata, recursion, ordering — which an agent would want before calling.

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% for the single 'dir' parameter, so the description is the only source of meaning — and it does supply concrete example paths (0:/gcodes, 0:/macros, 0:/sys) that the schema lacks. Still, it does not clarify path conventions (trailing slash, relative vs absolute, other volume prefixes) or whether the default is applied when omitted.

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 ('List files') plus the exact scope (the Duet SD card), which distinguishes it from machine-state siblings like get_status or get_sensors. It does not, however, distinguish itself from read_file, the other filesystem sibling, so an agent must infer the listing-vs-reading split on its own.

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?

No when-to-use statement, no prerequisites, and no named alternative (read_file is the obvious one for the same filesystem). The directory examples hint at typical usage but give no selection criteria between this tool and its siblings.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds enumeration domain (DirectShow/Windows) and the output-name convention, but says nothing about failure/empty-list behavior or what happens when no devices are found.

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 tight sentences with the core action front-loaded; the second sentence packs the device-name convention without preamble. No filler or restated title text.

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 list tool with no output schema, the description covers what is enumerated, the platform, and how to use the result — enough to call it correctly. It stops short of 5 only because nothing is said about the shape of the response (ordering, empty results).

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 for this dimension is 4. The description correctly adds no parameter detail because none exists, and instead documents the returned device-name format, which is the only input-like value an agent needs.

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?

Clear specific verb and resource: 'List video devices on the PC running this server', with platform scope (DirectShow, Windows) that pins down exactly what is enumerated. It does not explicitly contrast itself with the closest sibling, get_camera_snapshot, so it stops short of the top band.

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 real usage context: a phone-as-webcam appears in this list, and the returned name is consumed as DUET_CAMERAS="name=dshow:<device name>". It lacks explicit when-not guidance or a named alternative (e.g. 'use get_camera_snapshot to capture an image'), which keeps it out of the 5 band.

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?

Goes well beyond the annotations by disclosing the exact side effect: with fixes it writes a patched copy at <name>.duet.gcode and never modifies the original. This resolves the tension between the 'Read-only' phrasing and readOnlyHint=false (a write only occurs under explicit fix options).

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 purpose, then the check list, then the side-effect caveat. Dense but all sentences carry information; the long check enumeration is justified because it is the tool's actual 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?

No output schema, so the description must carry the result shape, which it does loosely by listing checks. It fully covers side effects and file outputs; the only gap is filamentDiameter and per-fix semantics.

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 50%, and the description compensates by naming the concrete fix values (select-tool, strip-g28) and their file-naming side effect. It says nothing about filamentDiameter, leaving one parameter undocumented in both places.

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+resource (check a local G-code file against this machine) and enumerates the concrete checks performed. This is clearly distinguishable from the read-only machine-query siblings like get_status or list_files.

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?

Explicitly frames timing as 'BEFORE uploading it' and names the conditional fix modes. It does not state when not to use it or point to an alternative tool, so it falls short of a 5.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: only text files are supported and the read is capped at 200 kB. It does not say what happens when the cap is exceeded or what errors occur on a missing path.

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 front-loaded sentence: action, resource, format examples, and limit. No filler, nothing that fails to earn its place.

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 could reasonably say more about the return (raw text content) and about failure modes such as oversized or binary files. For a simple one-parameter read it is adequate but leaves the truncation behavior ambiguous.

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 carries the burden for the lone 'name' parameter. The path examples (0:/sys/config.g, 0:/macros/...) give the expected format, which the bare string schema does not. It still omits whether relative paths or other roots are valid.

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?

Specific verb+resource: 'Read a text file from the SD card,' with concrete path examples (0:/sys/config.g, 0:/macros/...) and a size constraint. It is distinguishable from name alone, though it never explicitly contrasts with the sibling list_files, 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?

Usage is implied: read a single known file versus listing contents. There is no explicit 'use this when..., use list_files when...' routing, and no stated prerequisites (e.g., whether the file must already exist).

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