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

Annotations already declare readOnlyHint=false, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds practical context about locating the robot's IP, but says nothing about persistence of the addition, whether it overwrites an existing entry, or required connectivity state.

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 front-loaded sentence with a useful parenthetical hint; nothing is wasted. Slightly dense but appropriately sized for the action.

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 return values need not be explained, and annotations cover the safety profile. However, with 0% schema coverage the unmentioned team parameter and the absence of any note on duplicates or overwrite behavior leave a real gap for a state-mutating 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?

Schema coverage is 0%, so the description must carry the load. It successfully maps 'player name' to name and 'IP address' to host, but the third parameter, team (blue/orange enum with null default), is never mentioned, leaving it undocumented in both schema and prose.

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 (add) and resource (a robot on the team list), and ties it to the two identifying inputs. It is distinguishable from connect_robot or team_list by the 'team list' scope, though it does not name a sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when this applies and even tells the agent where to obtain the required host value (robot's Settings → Radio screen, or the control panel's Network menu). It stops short of stating when not to use it versus connect_robot/select_player.

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 destructiveHint=false, so the safe, advice-only nature is partly covered; the description reinforces this with 'without moving.' Beyond the annotations, it adds a genuinely useful behavioral caveat: the holding default comes from the onboard AI and often misses a held ball, so the agent should verify with look(). It does not describe latency or cost, but the key operational gotcha is disclosed.

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 purpose is front-loaded in the first clause, and the parenthetical enumerations of return content are dense rather than padded. It is a long run-on sentence with nested parentheses that could be split, but nearly every clause conveys substantive 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?

For a read-only advisory tool with no output schema, the description compensates well by enumerating what the advice contains (distances, roll times, path clearance). The main omission is speed_percent, but combined with annotations the agent has enough to call it correctly and interpret the result.

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?

With 0% schema description coverage, the description must carry all parameter meaning. It documents holding (defaults to onboard AI's view, unreliable for held ball) and teammates_mm (format [[x, y], …] and purpose 'teammates to pass to'), but speed_percent is never explained despite being a tunable input. Two of three parameters are covered, leaving a real gap on the third.

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 opening clause 'Strategy advice without moving: fetch, shoot, pass or dribble, and why' states a specific verb (advise) and resource (strategy decision) and immediately distinguishes it from action siblings like move, shoot_at_goal, and kick by declaring it is advice-only. It also previews the output content (distance to goal, kick roll distance, path clarity), so an agent knows exactly what kind of decision support it returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for invoking it (deciding between fetch/shoot/pass/dribble) and names an alternative tool to pair with: confirm the holding state with look() because the onboard AI often misses a held ball. It does not explicitly state when NOT to use it (e.g., inside a fast match loop vs. pre-planning), so it stops short of full alternative framing.

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 only declare readOnlyHint=false and destructiveHint=true; the description adds substantial context they do not cover: re-aiming per step, the kicker magnet holding balls and barrels, the AI losing the ball in the last ~10 cm and finishing on an estimate, and a photo returned unless the AI confirms success. This directly tells the agent what to verify before kicking.

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 sentences, front-loaded with the action and terminating condition, then prerequisites, then the failure caveat. Each sentence carries information, though the parenthetical about the magnet and the two-clause final sentence are slightly dense.

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, and the description covers the operation's key traits: preconditions, in-progress behaviour, physical outcome, and a conditional photo return the agent must inspect. For a destructive, no-required-parameter movement tool this is complete enough to call 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?

Schema description coverage is 50% (label and max_distance_mm documented, target enum and speed_percent not). The description reinforces the target/label choice ("Give a target kind or the label of an object or taught colour") but says nothing about speed_percent or the distance cap, so it only partially compensates for the 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?

States a specific verb and resource ("Drive up to an object the onboard AI can see") plus the terminal condition (until it's in the kicker). The mention of "re-aiming before every short step" and the magnet behaviour separates it from siblings like go_to, face_object, and fetch_ball without needing to open 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?

Explicitly routes the agent to alternatives when the precondition fails: "If it isn't in view, use face_object or scan_surroundings first." However, it does not distinguish approach_object from neighbouring movement tools such as go_to or explore_arena, so it is clear context without full when-not coverage.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: that most tools auto-connect and that this call can be used as a recovery path. It does not describe failure modes or what a successful/failed connect returns, so it stops short of full transparency.

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, both load-bearing: the first defines the action, the second gives the conditions. Nothing is repeated from the title or annotations and the key scoping fact is front-loaded.

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-required-parameter connection tool with no output schema, the description covers the decision an agent must make (do I even need to call this?) and is arguably more important than any return value. It is slightly incomplete in not indicating what happens if the connection attempt fails or how the agent should react.

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 single 'host' parameter is already documented as "IP address or hostname, if not the configured robot." The description adds no syntax, format, or fallback semantics beyond that, so the baseline 3 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 gives a specific verb (connect/reconnect) and resource (the robot), and explicitly distinguishes itself from the auto-connecting siblings. An agent can immediately tell this apart from disconnect_robot and from the motion tools that connect implicitly.

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 both when the tool is NOT needed ("Other tools connect automatically") and the two narrow conditions when it IS needed (switching robots, recovering a dropped connection). This is explicit when/when-not guidance rather than implied usage.

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 declare readOnlyHint=false, openWorldHint=false and destructiveHint=false, and the description adds real behavioral context beyond them: the panel is a live shared surface whose person-side choices are readable via robot_status().panel and wait_for("panel"), and it can be toggled off via close. It does not cover persistence, what closing does to in-flight selections, or whether opening is idempotent.

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 core action and the panel's contents, then the browser routing, then the state-sharing hook. The feature enumeration is longer than strictly needed for selection, but each clause is informative 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?

With no output schema, the description correctly explains how results come back (robot_status().panel, wait_for("panel")), which is the key missing piece for a tool that opens a UI. Minor gaps remain around idempotency and side effects of closing the panel.

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 goes beyond the schema by explaining the practical decision behind open_browser (built-in browser present vs absent) and implying the enabled toggle via 'open (or close)'. yolo_detection's ~10 s first-load cost is left to 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?

States a concrete verb (open/close) and a specific resource (the control panel web page), then enumerates what the panel actually contains (live camera, detection boxes, team buttons, labelling, colour teaching, STOP, map, log). Nothing else in the sibling list does this, so disambiguation is unambiguous.

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 operational routing: show the URL in the app's built-in browser, otherwise give the person the link, or set open_browser. This tells the agent how to invoke it in different hosts, but it never states when this tool should be preferred over siblings (e.g. versus look, detect_objects, robot_status) or any condition for not using it.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavior beyond that: it discloses the return content ('with bearings') and the cost/latency characteristic ('without fetching a photo'), which is real context an agent can act on.

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 tight sentence that is front-loaded with the core action and carries the two most decision-relevant facts (bearings, no photo). No waste, nothing redundant.

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 carry return-shape info, and it does convey that results are a list with bearings. Combined with the annotations and fully documented parameters, an agent has nearly everything needed; only finer details of the returned fields/format are unstated.

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%, with both 'source' (enum) and 'apriltags' fully documented in the schema. The description adds nothing about parameters, so the schema does the heavy lifting and the baseline 3 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 states a specific verb and resource ('List what the robot can see') plus a distinguishing trait ('with bearings, without fetching a photo'). This implicitly separates it from photo-returning siblings like 'look' or 'scan_surroundings', though it does not name those alternatives directly.

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 phrase 'without fetching a photo' implies the tool is for lightweight/cost-free perception rather than image capture, hinting at when to prefer it over 'look'. However, no explicit when/when-not guidance or named alternative is given, so the routing is left to inference.

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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=false — they do not explain the connection lifecycle. The description adds real behavioral context beyond them: the disconnect is reversible because "Tools reconnect automatically," so the agent knows the handoff is non-permanent. It does not cover permissions or the state when already disconnected.

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, zero waste, with the core action front-loaded and the side-effect (auto-reconnect) immediately after. Nothing could be trimmed without losing 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, no-output tool with annotations covering the safety profile, the description supplies what is needed: the effect and the fact that the connection self-restores. Only minor gaps remain, such as behavior when the robot is not currently connected.

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 is nothing for the description to disambiguate, and it introduces no spurious 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 verb ("Release") and resource ("the robot"), and clarifies the intent: handing the robot off to VEXcode or a Python script. The sibling connect_robot is implicitly the inverse, but the description never names it explicitly, so differentiation rests on the tool name rather than the text.

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?

"Release the robot so VEXcode or a Python script can use it" gives a clear condition for calling it, and "Tools reconnect automatically" tells the agent it does not need to follow up with connect_robot. There is no explicit when-not guidance (e.g., behavior if already disconnected), but the context is unambiguous.

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 cover the write/safety profile (readOnlyHint=false, destructiveHint=false), but the description adds state the annotations cannot convey: motion is locked on every connect and requires user consent before unlocking. It stops short of describing what happens if the call is made unsafely or any rate/scope limits.

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 sentences, zero padding, front-loaded with the action and the unlocked capability set before the safety constraint. Every sentence 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?

No output schema is needed for a one-parameter enablement toggle, and the description fully covers the lock/unlock lifecycle and the consent precondition. Nothing an agent needs to call this safely 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 boolean is already documented, but the description reinforces its intent by pairing 'Ask the user first' with the confirmation gate, tying the parameter to a real-world consent requirement rather than leaving it as a bare flag.

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 (unlock/enable) plus the exact resource and the enumerated capabilities it gates: move, turn, turn_to_heading, face_object, kick. An agent can distinguish this from the individual sibling tools it unlocks.

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 states when to call it ('Ask the user first; never call this on your own initiative') and gives the rationale (motion starts locked each connection because the robot may be on a table). This is a clear when/when-not directive with no inference required.

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?

Despite annotations already flagging destructiveHint=true, the description adds substantial behavior: obstacle and existing-map avoidance, spot-skipping logic, stopping on a bump, a multi-minute runtime, the STOP-button escape hatch, and where results land (robot_status().panel.map). This is exactly the kind of operational context annotations cannot convey.

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?

Purpose is front-loaded in the first clause, and the dense sentences all carry real information. It is somewhat run-on with stacked parentheticals, but little 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?

With no output schema, the description usefully redirects to robot_status().panel.map for results, and it covers failure modes and duration. The only real hole is the undocumented speed parameter, leaving it slightly incomplete for a tool that drives the robot.

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 parameter speed_percent is never mentioned in the description and the schema has 0% description coverage, so the agent learns nothing about its effect, units, or the 5-100 bounds from prose. The name is fairly self-explanatory, which keeps this above a 1, but 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 states a specific verb and resource ('Map the arena by driving around it') and immediately elaborates the mechanics. It is clearly distinguishable from siblings like scan_surroundings or go_to, which do not build a map.

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 one conditional ('Without a field it only scans where it is'), which implies when the tool is worthwhile, but it never explicitly contrasts with scan_surroundings or other mapping-adjacent siblings, nor states when not to use it. 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?

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=false, and the description does not contradict them. The description adds useful context about what the vision can recognize, but it never explains the notably aggressive destructiveHint=true on a turn-in-place action, nor what happens if the object is never 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 sentences, front-loaded with the core action before the capability list. No filler or redundancy. Slightly dense enumeration in the second sentence but every item is informative.

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 4-parameter action tool with no output schema, the description covers purpose, capabilities and one prerequisite, but omits outcome semantics: whether it reports the object found, distance/heading, or how failure to find is signalled. An agent can call it, but cannot predict what comes back.

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 only 50% (label and search are documented; target and speed_percent are not). The description compensates by enumerating the recognizable target classes that map to the target enum, and by clarifying that labelled/taught-colour objects go through the label path. It still says nothing about speed_percent behaviour.

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 concrete verb+resource: find an object via onboard vision and turn to face it. It also enumerates what the vision can target (sports balls, barrels, AIM robots, AprilTags, labelled objects, taught colours), which scopes the tool precisely. It stops short of explicitly distinguishing itself from close siblings like approach_object or detect_objects.

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 context for when this applies: objects the onboard AI knows, labelled objects from the control panel, or colours previously taught via teach_colour. That names a prerequisite sibling tool, which helps the agent sequence calls. There are no explicit exclusions or named alternatives for cases where the object isn't recognizable.

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 only declare the safety profile (readOnly false, destructive true, openWorld false); the description adds substantial operational context: the multi-step motion plan, obstacle avoidance, the known last-~10cm ball-loss failure mode, the recovery path via look(), and STOP as the terminator. This is rich behavioral disclosure well beyond the annotations.

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 core action and sequence before the caveats, and every sentence carries information (process, sibling differentiation, failure mode, termination). It is dense but not padded, though the parenthetical detail about the control panel's map is slightly tangential.

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 usefully characterizes the result state ('can't confirm the ball is held') and the recovery action, and it covers the failure mode and termination. The only real gap is the unexplained speed_percent parameter, which leaves an agent unable to reason about its default.

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 parameter speed_percent (default 40, range 5-100) is never mentioned in the description, so its units, effect on behavior, and safe values are undocumented anywhere. The description fails to compensate for the low coverage.

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 concrete verb+resource (fetch the ball into the kicker) and unpacks the full behavioral sequence: locate, drive to just short of it around obstacles, creep up with the camera. It explicitly distinguishes itself from the sibling approach_object by noting the ball needn't be in view.

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?

Names the alternative (approach_object) and the condition that selects this tool over it — the ball need not be in view. It also prescribes a recovery step (check with look() if the result can't confirm the ball is held) and notes STOP terminates it, though it doesn't state when to prefer approach_object 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?

Annotations only give readOnly=false, destructive=true, openWorld=false; the description adds substantial context they don't carry: obstacle avoidance, termination accuracy (within a few cm), the origin used for coordinates, and an explicit refusal rule (off-field or within 10 cm of walls). It does not, however, explain what the destructiveHint refers to or what happens on refusal (error vs. no-op).

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?

Compact, front-loaded with the primary action and destination, then the optional heading and the refusal constraint. The parenthetical about the coordinate origin is slightly tangled but every clause carries 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 4-parameter motion tool with no output schema, the description covers origin, precision, heading behaviour and rejection conditions, but leaves speed_percent undefined and does not say whether a failed/refused drive raises an error or returns a partial result. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It usefully defines the coordinate frame for x_mm/y_mm and explains heading_deg semantics (optional, 0 = up the field, applied at the end), but speed_percent is never mentioned and its 5–100 range/default of 40 is left entirely to the bare 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 (Drive) and a specific destination resource (a spot at field mm coordinates), plus the movement behaviour (obstacle avoidance, few-cm accuracy). This is clearly distinguishable from siblings like move, turn, turn_to_heading and explore_arena 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?

The description clarifies the coordinate frame ('field mm when a field is chosen in the control panel, otherwise from where the robot connected'), which is genuine usage context, but it never names an alternative tool or states when to prefer go_to over move/approach_object/explore_arena. Usage is implied rather than prescribed.

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 destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating action. The description adds real behavioral detail (position 25 cm in front of the goal, slide between ball and centre, end early on catch), but it never explains what the 'destructive' trait means here - e.g. that it takes over control for up to `seconds` and preempts other commands.

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 front-loaded sentence with the verb first and the mechanics following; the parenthetical clarification earns its place. Slightly long and clause-heavy but free of 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?

No output schema exists, and the description is behaviorally complete for the motion itself, including the termination condition. However, for a destructive control-taking tool it omits blocking/timeout semantics tied to `seconds`, and gives no parameter interpretation against a 0%-coverage schema.

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% across 3 parameters, so the description must compensate and largely doesn't. The prose touches goal-side logic ('the blue team guards the orange goal') but never explains the `goal` enum values including the default `defend`, and `seconds` and `speed_percent` are not mentioned at all.

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 behavior ('Play goalkeeper for a while') and spells out the stand-and-slide mechanics, so the agent knows this is a high-level autonomous behavior, distinct from primitive siblings like move/turn. It does not name a contrasting sibling, but the purpose itself is unambiguous.

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 by the phrase 'Play goalkeeper for a while', suggesting a defensive situation, but the description never says when to choose this over manually combining move/face_object/stop, nor when not to use it. No prerequisites or alternatives are named.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real beyond-annotation context: the kick fires at whatever is held, balls bounce and can rebound toward the robot, and backing away is specifically to keep the magnet from recapturing a returning ball. That explains the destructive/motion behavior rather than restating it.

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 tight sentences, front-loaded with the action, then safety, then the verification tool. Every sentence carries information; there is no filler or 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 mutation tool with annotations covering the safety profile and no output schema, the description covers the action, the recoil behavior, and the verification step. It stops short of saying what happens if the kicker holds nothing or how failures surface, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, and the described parameter (back_away_mm) already carries its own schema description. The description only adds meaning for the 'soft' enum value, saying nothing about 'medium' or 'hard', so it partially compensates for the undocumented strength enum but not fully.

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 gives a specific verb and mechanism: firing the kicker at whatever it is holding, plus the 'soft' variant for gentle pushes/places. It is clear what the tool does, but it never differentiates itself from the many action-oriented kick siblings (shoot_at_goal, pass_ball, test_kick), leaving the agent to infer the distinction.

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 offers practical preconditions (aim at open space, ensure no one is in the way) and names look() as the way to verify the kicker is holding something. However, it gives no guidance on when to use kick versus shoot_at_goal or pass_ball, so the routing decision among kick siblings is left unresolved.

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 (readOnly, non-destructive), so the description's job is to add content semantics — and it does, listing the recognised classes and the bearing ruler. It stops short of stating exactly what is returned (image vs structured detections) and omits the on-demand YOLO 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?

Two tight sentences, front-loaded with the action and immediately followed by what the agent will see. No filler, though the second sentence carries two ideas (detections and the ruler) that could be split for speed of scanning.

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 usefully explains what the photo contains and how to derive bearings for unrecognised objects, which is the key thing an agent needs. It is not fully complete since the yolo_detection option and the exact return shape are unaddressed.

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 both parameters are already documented in the schema. The description references the ruler that the 'overlay' parameter controls, but adds no new detail about the overlay toggle or the yolo_detection option, so baseline 3 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 states a concrete verb and resource (take a photo with the front camera) and clarifies the outcome (you see it yourself). It is clear on its own, though it never names siblings like detect_objects or scan_surroundings to distinguish overlapping capability.

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 explicit guidance on when to use this versus detect_objects or scan_surroundings, which are close functional siblings. The only routing hint is 'for anything else, read its bearing off the ruler,' which is about interpreting the output rather than choosing the tool.

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 flag destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the call blocks until motion completes, and it terminates early on a bump. It does not explain why the operation is destructive or what happens on abort, but the blocking and collision behavior are valuable disclosures.

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, both front-loaded with the core action and then the blocking/abort behavior. No filler, no repetition of the title.

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 three-parameter motion tool with no output schema, the description covers the two critical unknowns an agent must know before calling: that it blocks and that it can abort on contact. The remaining gap is what the call reports back (success vs. bump-abort), which the absence of an output schema leaves unaddressed.

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 distance_mm, direction_deg, and speed_percent are fully documented in the schema, including the direction convention and speed scaling. The description only echoes 'a set distance in any direction' and adds no syntax or format detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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 gives a specific verb and resource: 'Drive a set distance in any direction, then stop.' That is unambiguous and distinguishes it from rotational siblings like turn and turn_to_heading, and from goal-oriented siblings like go_to or approach_object, though it never names those alternatives explicitly.

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 or when-not-to-use guidance and no routing to alternatives. An agent cannot tell from the text when to use this primitive versus go_to, approach_object, or explore_arena; the collision-abort sentence is behavioral, 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 declare the safety profile (destructiveHint=true, not read-only), and the description adds meaningful behavior beyond that: it fetches the ball if distant, dribbles when no measured kick suffices, and refuses when the path is blocked. It does not discuss permissions, failure surface, or what a refused call returns, so it is strong but not exhaustive.

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 sentence that front-loads the verb and purpose before elaborating on units and fallbacks; nothing is padding. It is slightly run-on, packing three conditional behaviors into one clause chain, which costs a little readability.

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 and annotations covering only safety, the description supplies the coordinate frame, fallback strategy, and refusal semantics an agent needs. The undocumented speed_percent parameter and the absence of any return-value or failure detail are the remaining gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the load, and it does define the coordinate system and units for x_mm/y_mm precisely ('mm... (0,0) is its centre, x right, y up the field'). speed_percent, however, is left completely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Kick the ball to a spot on the field') and immediately pins down the coordinate frame, which distinguishes it from siblings like kick, shoot_at_goal, and fetch_ball. An agent can tell what this does without opening the 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?

Describes the internal fallback chain (fetch first if needed, dribble closer if no measured kick reaches) and the refusal condition, giving clear context for when the tool applies. It never names an alternative tool or an explicit when-not-to-use case, so it stops short of full routing guidance.

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

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

With annotations already covering safety (non-destructive, closed-world, non-read-only), the description adds important behavioral detail: it blocks until playback finishes and caps the wait at 30 seconds. It does not describe timeout fallback or note parsing failures, but it is substantively better than annotations alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single front-loaded sentence with no waste; the max-duration caveat is appropriately placed.

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 two-parameter audio tool, the description provides the critical blocking/timeout context, annotations cover safety, and the schema details the notes format. It omits any volume mention and timeout behavior, so it is not fully complete, but adequate.

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 50%: notes are richly documented in the schema, while volume is only bounded/defaulted. The description adds no parameter meaning for either notes or volume. The schema carries the usable semantics, so this is adequate but not enriched by the description.

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 ('Play') and resource ('tune on the robot's speaker'), and adds the blocking duration. It does not explicitly distinguish this from sibling audio tools such as play_sound or say, 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?

No when-to-use guidance and no conditions for choosing this over play_sound, say, or other audio-output siblings. The description explains behavior but not context.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's phrase 'built-in sounds' usefully confirms no external resource is fetched, consistent with openWorldHint=false, but it says nothing about playback duration, blocking behavior, or whether overlapping sounds are possible.

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 compact sentence with no waste. It is appropriately sized, though its brevity comes at the cost of missing detail rather than through disciplined editing.

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 and zero schema description coverage across two parameters, the description leaves the volume parameter and the meaning of the sound enum undocumented. For a tool whose main decision surface is choosing a sound and level, this is a clear gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, yet it only gestures at the 'sound' argument and never mentions the 'volume' parameter at all. The 29 enum values are listed dryly in the schema with no indication of what each sound conveys.

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 ('play ... sounds') and scopes it to the robot's built-in sound set, which distinguishes it from siblings like play_notes and say. It does not explicitly contrast with those siblings, but the resource is unambiguous.

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 guidance on when to use this tool versus play_notes, say, or show_emoji, no prerequisites, and no conditions or exclusions. The agent must infer usage context from the name alone.

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 annotations only covering safety flags (readOnlyHint=false, destructiveHint=false), the description carries the behavioral burden and does add real context: the card auto-reverts to the resting face after a few seconds, and the name/team colour are pulled from the control panel (a cross-tool dependency). It also reveals a side effect on the lights, which overlaps with set_lights, but doesn't say whether this blocks, whether it fails if the robot is disconnected, or whether it overrides show_emoji/show_text.

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 sentences, front-loaded with the core action and content, then use cases, then the auto-revert caveat. The enumerated game examples are slightly verbose but earn their place by mapping events to expressions. No filler or restated title.

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 3-optional-parameter, no-output-schema tool, the description covers what is displayed, where the name/colour come from, the default caption behaviour, and the auto-revert timing. Remaining gaps are error/precondition behaviour (robot connection) and interaction with the other display tools, but the essentials for correct invocation are present.

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 67% (hold_s and caption documented there; the expression enum has no per-value description). The description compensates by illustrating which expressions map to which game situations and by restating the revert behaviour ('goes back to the resting face after a few seconds') that gives hold_s meaning. It omits the 'focused' enum value present in the schema, a minor 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 gives a concrete verb and resource ('Show the player card on the robot's screen') and enumerates exactly what the card contains: expression face, player name, team colour from the control panel, and lights in team colour. This composite nature implicitly distinguishes it from siblings like show_emoji, show_text, and set_lights, though it never names those alternatives explicitly.

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 concrete when-to-use context tied to game events ('excited after a goal, sad after a miss, wink after a good pass, surprised after a bump'), which tells the agent the intended scenarios. It stops short of explicit exclusions or naming the sibling tools (show_emoji/show_text) that an agent might otherwise pick, so no routing rule is 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?

Annotations already declare readOnlyHint=false, openWorldHint=false, and destructiveHint=false, so the write-but-safe profile is covered. The description is consistent with these and adds the triggering scenario, but says nothing about repeat calls, overwriting, or persistence semantics beyond the annotations.

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 sentence with the action front-loaded and the context trailing as an example. No filler, though the phrasing is slightly informal ('someone measured').

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 two-parameter write tool with annotations and no output schema, the core is present. It still leaves open what happens on repeated saves and gives no parameter guidance, which a recording tool should ideally clarify.

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%: distance_cm carries a schema description, but strength (an enum) is undocumented there. The description adds no information about either parameter, so it fails to compensate for the coverage gap; the self-evident soft/medium/hard values are the only reason this isn't a 1.

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 ('Save') and resource ('kick distance'), so an agent knows this persists a measurement rather than performing a kick. It references test_kick as the source scenario, giving some separation from siblings like kick and test_kick, though it doesn't fully distinguish itself from other recording tools.

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 example 'after test_kick lost sight of the ball' gives one concrete trigger scenario, which implies when to use it. However, there is no explicit statement of when not to use it, nor a named alternative for other recording paths.

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 disclose that this is a non-read-only, non-destructive, closed-world operation, and the description adds the concrete state change (heading to 0°, position to (0, 0)). However, it does not resolve the critical ambiguity for a robot: whether the physical robot moves to the origin or only the internal coordinate frame is re-zeroed.

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 tight sentence with no filler, front-loading the two effects. Nothing is wasted and nothing relevant to a zero-argument tool is omitted.

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 parameters, no output schema, and annotations covering the safety profile, the description is nearly sufficient. The remaining gap is whether this is a physical motion or a logical frame reset, which matters for sequencing against move/turn in a robot control flow.

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 correctly implies no arguments are 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?

States a specific effect with exact values: heading becomes 0° and position becomes (0, 0). This distinguishes it from turn_to_heading (sets an arbitrary heading) and go_to (moves to an arbitrary position), though it does not name those siblings explicitly.

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 explicit when-to-use or when-not-to-use guidance, but the semantics strongly imply the use case: re-zeroing odometry so heading and coordinates start from a known origin. The agent must infer this rather than being told.

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 cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is to add beyond that. It does: it discloses that the tool auto-connects if needed and warns that the 'holding' signal relies on onboard AI and is unreliable in dim light — a real behavioral caveat not present in structured fields.

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 full list of reported fields, then the connection note, then the reliability caveat. Dense and mostly waste-free, though the enumeration is long and reads as a run-on clause rather than tight sentences.

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 burden of describing returns and does so by enumerating the reported fields. Combined with the connect and reliability notes, an agent has enough to call it correctly, though it omits return format/units.

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. The description correctly implies a parameterless snapshot with no configuration to supply.

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?

Names a specific resource (the robot) and enumerates exactly what the status readout covers: battery, heading, position, tilt, motion, sound, kicker holding, and onboard AI vision. This is far more specific than sibling tools like detect_objects or scan_surroundings, letting an agent distinguish it immediately.

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 explicit operational context ('Connects if needed') and routes to an alternative when the report is unreliable ('often misses a held ball in dim light; use look()'). It stops short of a full when-to-use matrix against every sibling, but the key failure-mode routing is present.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful channel context (audible output via the robot speaker using macOS TTS), but says nothing about whether speech blocks subsequent actions, overlaps motion, or can be interrupted.

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 tight sentence that front-loads the action and output channel with no filler. It is efficient, though its brevity contributes to the gaps in usage and behavior disclosure.

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 single-required-parameter tool this is close to adequate, and no output schema means return values need not be explained. However, with no blocking/interruption semantics and no routing against the other audio and reaction siblings, an agent is left guessing about integration behavior.

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 67%: text and voice are documented in the schema, but volume carries only default/min/max with no explanation. The description adds no parameter meaning at all, leaving the uncovered parameter unaddressed.

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 (speak out loud) and resource (robot's speaker / Mac text-to-speech), which is clear enough to distinguish from audio siblings like play_sound and play_notes. It does not name those siblings explicitly, so differentiation is implied rather than stated.

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 guidance, no exclusions, and no mention of the adjacent audio tools (play_sound, play_notes, react) an agent would need to choose between. The agent must infer selection criteria from the name alone.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds meaningful behavior (full rotation, return to starting heading, recognising AprilTags only once enabled), but never explains why a scan is destructive (e.g. collision risk while turning), which is the one surprising trait the annotations flag.

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, behavior first and usage second, front-loaded with no filler. The parenthetical object list is long but functional; overall 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?

With no output schema, the description usefully spells out what the scan yields (object headings and goal centres) and the workflow to follow. It is only incomplete on the undocumented speed parameter.

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 parameter speed_percent has 0% schema description coverage and the description never mentions speed or its range/default. Nothing compensates for the gap, leaving the parameter's meaning to be inferred from its name and bounds alone.

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: 'Turn a full circle on the spot,' then names exactly what it captures (headings of recognised objects and centred goals). This distinguishes it from siblings like look and detect_objects by describing the 360-degree sweep and heading output.

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 tells the agent what to do with the result: 'Use the headings with turn_to_heading, approach_object or shoot_at_goal.' Clear downstream context, but no guidance on when to prefer this over look/detect_objects or any exclusions.

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 destructiveHint=true and openWorldHint=false, but the description adds substantial behavior: it is a multi-step autonomous routine, it sources the goal from the map or by looking around, its kick strength depends on prior test_kick measurements, and it degrades to dribbling to 30 cm plus a soft kick when none exist. These side effects and fallbacks are not derivable from structured fields.

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 routine is front-loaded as a single sequence of actions and each clause carries operational content, so the length is justified by the tool's complexity. A few phrasings are slightly verbose but nothing is 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?

With no output schema, the description carries the return-behavior burden and describes the multi-step process and fallback well; annotations cover the safety profile. The main gap is the absence of any coverage of the two input parameters, which is the one thing an agent must still resolve from the schema.

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% for two parameters, so the description must carry the semantics and largely does not. It never explains the 'goal' enum values (team/blue/orange) or the default, and speed_percent is only obliquely echoed by 'gentlest measured strength' with no reference to the 5-100 range. The agent is left to infer parameter meaning from the schema alone.

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 lays out the full autonomous routine with concrete verbs (fetch, find, dribble, line up, kick, back away) rather than restating the name. It is unmistakably distinct from the sibling shoot_at_goal, which it explicitly contrasts. An agent knows exactly what this tool accomplishes without reading the 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?

It names the alternative (shoot_at_goal) and the condition that separates them ('instead kicks from where the robot stands'), discloses the dependency on test_kick measurements and the fallback when none exist, and states a precondition ('Make sure nobody is near the goal'). When-to-use, when-not, and prerequisites are all covered.

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 mark this as a non-read-only, non-destructive, closed-world mutation. The description adds genuinely useful behavior beyond that: it changes the active target for all other tools, motion is locked per robot, and a human confirmation is expected before enable_motion. It does not describe failure modes or what happens to the previously selected robot.

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 core action, and the prerequisite warning follows logically. No filler, though the phrasing is slightly indirect.

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, no annotations on parameters, and 0% schema coverage, the description covers purpose and the enable_motion prerequisite but leaves the meaning and format of 'name' entirely unexplained. Adequate but with a clear gap for a tool whose only input is 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 coverage is 0% and the single 'name' parameter is undocumented in the schema. The description only implies the name identifies another player's robot; it never states the format, whether it is a player name, team name, or robot ID. It does not 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 states a specific verb and resource: making another player's robot the target that tools and the control panel act on. It is clear what the tool does, though it does not explicitly name or distinguish itself from nearby siblings like connect_robot or add_player.

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 sequencing context: motion starts locked on each robot, so the user should confirm the robot is on the floor before calling enable_motion. This tells the agent when this tool fits into the workflow, but it offers no explicit when-not conditions or direct alternatives.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful physical context that the ring has six lights, but says nothing about persistence, whether a light setting survives other commands, or what the optional defaults do when no arguments are supplied.

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 with no filler. Everything an agent needs at a glance is in the first clause, and nothing is repeated from the schema or annotations.

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 two-parameter tool with full schema coverage, no output schema, and clear annotations, the description is nearly sufficient. The only real gap is that both parameters are optional with defaults, so calling it with no arguments silently sets all six lights green - behavior the description does not surface.

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%: the led enum documents each position (front-left through front-right) and the color parameter lists all accepted colour names plus hex syntax. The description's 'ring of six lights' slightly reinforces how to interpret the led index, but adds no format or constraint detail beyond the schema, so the baseline 3 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 gives a specific verb ('Set') and resource ('the colour of the robot's ring of six lights'), making it immediately distinguishable from the motion, audio, and vision siblings. It stops short of naming any alternative tool, but none of the siblings overlaps with light control.

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 guidance on when to use this tool, no prerequisites, and no mention of alternatives. Usage is only implied by the verb itself.

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=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds meaningful domain behavior — that setting a team determines which goal the robot scores in — but doesn't state whether the choice persists across games or can be changed mid-game.

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 core action is front-loaded in sentence one, with supporting scoring context and the control-panel alternative afterward. Slightly verbose, but every sentence contributes relevant 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 single-enum-parameter tool with annotations and no output schema, the description supplies enough context to call it correctly. Persistence/reversibility of the choice remains the only notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the burden, and it does partially compensate by explaining that 'colour' defines the team and its associated goal/barrels. The enum values themselves are self-documenting, so this is close to adequate.

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 ('Choose the robot's team') and frames it in a distinct scenario (start of a goal game). It is easily separated from siblings like team_list and select_player. The scope is unambiguous.

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 timing ('at the start of a goal game') and names an alternative path ('the person can also pick the team in the control panel'). It is missing explicit when-not guidance, but the context and alternative are stated rather than 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write/destructive nature is covered. The description adds meaningful behavior beyond that: the multi-step physical sequence, the post-action retreat, and the fact that it returns a photo taken after the kick. It does not describe failure conditions (e.g., no goal visible, ball not in kicker).

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 sentences, front-loaded with the core action and followed by prerequisites and return value. Efficient, though the second sentence's nested parentheses make it slightly dense rather than maximally scannable.

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 usefully discloses the return value ('a photo taken after the kick'), covers prerequisites, and outlines the behavioral sequence. For a 3-parameter, zero-required tool it is nearly complete; missing only edge-case behavior on failure.

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 67%: goal and strength enums carry their own descriptions while speed_percent is undocumented. The description adds no parameter-level meaning (no mention of goal colour selection, strength choice, or speed), so it does not compensate for the coverage gap. Baseline 3 is appropriate.

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 gives a specific verb and resource ('Score with the ball the robot is holding') and unpacks the full sequence of actions (find goal, turn, kick, back away). It does not explicitly contrast itself with closely related siblings like score_goal, kick, or test_kick, so an agent must infer the distinction.

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 clear preconditions and routes to alternatives: 'Get the ball into the kicker first (approach_object) and confirm with look().' This is explicit prerequisite guidance naming sibling tools. It lacks any when-not-to-use or failure-mode guidance, 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=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds the useful 'none hides it' behavior, but says nothing about what happens to prior screen content, whether a connection is required, or the effect of repeated calls.

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 core action front-loaded and the special-case value appended in parentheses. No wasted material, though it is arguably under-specified rather than genuinely concise.

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 only two enum parameters, no output schema, and safety already covered by annotations, the definition is close to adequate. However, it omits any meaning for 'look' and gives no hint of the mutation's effect or return, leaving a real gap for a screen-state-changing 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies that 'none' hides the emoji, but the 'look' parameter (forward/left/right) is never explained, leaving one of two parameters undocumented in both schema and description.

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 ('Show') and resource ('the robot's animated faces on its screen'), so an agent can tell this apart from show_text or set_lights by the visual-face emphasis. It does not explicitly name a sibling, but the purpose is unambiguous.

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 guidance, no mention of alternatives (e.g., show_text vs show_emoji), and no stated preconditions such as needing an active connection. The agent is left to infer usage entirely from the purpose line.

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 declare readOnlyHint=false but destructiveHint=false, so they don't surface that this overwrites prior content. The description explicitly says it replaces whatever was on screen and that long lines wrap, which is real behavioral context beyond the structured fields.

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 no filler; the primary effect (write text, replacing content) is front-loaded before the wrapping detail.

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 display tool with no output schema, the description covers the core behavior, target screen, and overflow handling. The main omission is guidance on the undocumented size/color/background parameters.

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 only 25%: text is documented, but size, color, and background have no descriptions. The description adds the screen dimensions and wrapping behavior but says nothing about the enum size options or how color/background interact, so it does not 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?

States a specific verb and resource: write text on the robot's 240x240 screen. The screen medium clearly separates it from siblings like say (speech) and show_emoji (icons), though it doesn't name any 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?

No when-to-use guidance and no routing to alternatives such as say for spoken output or show_emoji for an icon. The usage is only implied by the description of the effect.

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 destructiveHint=true and readOnlyHint=false. The description adds valuable context beyond annotations: it works even while motion is locked, and it interrupts ongoing exploration or experiments. It does not detail side effects like goal cancellation or return values, but the additions are meaningful.

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 core action and zero wasted words. The most important constraint ('Always allowed, even while motion is locked') follows immediately and is clearly separated.

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, no-output-schema stop command with annotations covering destructiveness, the description supplies the essential behavioral context: it stops all motion immediately, can interrupt ongoing tasks, and is always permitted. Nothing critical for correct invocation 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 no parameters, so the baseline is 4. The description does not need to explain parameter semantics, and it correctly avoids inventing any.

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?

Clearly states a specific verb and resource: 'Stop all motion immediately.' It also specifies scope by including 'an exploration or experiment in progress,' which helps distinguish it from motion commands like move or turn. However, it does not explicitly name alternatives such as reset_position, so sibling differentiation is implicit rather than stated.

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?

Provides a condition ('Always allowed, even while motion is locked') but does not explain when to choose this tool over alternatives like reset_position. Usage is implied: call when you need to halt all motion. No exclusions or named alternatives are given.

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 declare a non-destructive, non-open-world write, so the safety profile is covered. The description adds real behavioral context beyond that: the robot tracks the colour autonomously many times a second, the label becomes a reusable identifier, and the robot holds only 7 signatures — a capacity constraint an agent needs. It doesn't say what happens when the 7-slot limit is exceeded or whether re-teaching overwrites.

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 sentences, front-loaded with the core purpose, then the persistence/label-reuse consequence, then the capacity detail. Efficient with little waste, though the VEXcode AI Vision Utility reference is slightly tangential.

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 4-param mutation with no output schema, the description covers purpose, autonomous tracking behavior, label reuse, and the 7-signature capacity. It omits return values, overwrite/error behavior, and any note on the undocumented tolerance parameter, but is largely complete for its complexity.

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 75%: label, box_xyxy and width_mm are all documented in the schema, and box_xyxy even includes the 'well inside the object' sampling advice. The description adds only that sampling comes from the current camera view. The 'tolerance' enum is undocumented in both schema and description, so the description does not compensate for that 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?

States a specific verb+resource ('Teach the robot's onboard AI to detect a colour') and clarifies the sampling source (part of the current camera view). An agent can distinguish this from sibling tools like detect_objects or look without opening a 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 context for when to use it — sampling a colour from something spotted in a look() photo — and explains the payoff (label reusable in approach_object, face_object, wait_for). No explicit exclusions or statement of when not to use it, so it stops 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the semantics of "selected" and the visibility report (teammate/opponent/unknown), which are genuine behavioral additions an agent cannot get from the annotations.

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 returned field list and followed by the "selected" semantics. Slightly awkward opening phrasing ("The robots on the team list") but no filler sentences; every clause carries 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?

With no output schema, the description must carry the return-value burden, and it does so field by field, including the visibility report. Minor gaps remain (ordering, count, or how unknown detection works), but the agent has enough to interpret the result.

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. The description correctly adds nothing about inputs and instead spends its words on outputs, which is the right use of space for a no-arg tool.

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 and enumerates exactly what is returned: each player's name, team, robot address, connection state, battery, and field position. It is clearly a read/enumeration tool, but it never explicitly differentiates itself from the sibling robot_status (single-robot view), leaving the boundary to inference.

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 explains the meaning of "selected" and routes the agent to select_player for switching, which is useful orientation. However, it gives no explicit when-to-use guidance relative to robot_status or other state-reading siblings, so the choice among them remains 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 annotations only declaring destructive/openWorld/readOnly hints, the description adds substantial undisclosed behavior: the distance is persisted when the ball stops in view, an out-of-range roll requires human measurement, and results accumulate in robot_status().panel.abilities. It does not explain the destructiveHint=true side effect (the robot physically displaces the ball), leaving one notable 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?

The purpose and the open-floor precondition are front-loaded, and each subsequent sentence adds a distinct fact (persistence, human fallback, where results land). Slightly conversational phrasing ('watch it roll') costs a little density but nothing is 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 tool with no output schema, the description does the important work of saying where results are stored (robot_status().panel.abilities) and what to do on failure. The main omission is any hint about the strength enum's semantics or the physical side effect implied by destructiveHint=true.

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 50%: the `ball_in_kicker` parameter is documented in the schema, but `strength` has only an enum with no explanation. The description says 'how far this strength sends it', linking the parameter to an effect, but never clarifies what soft/medium/hard mean or how they map to distance. Baseline 3 fits since the schema carries roughly half the load.

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 action ('kick the ball in the kicker straight ahead and watch it roll') and its goal ('to measure how far this strength sends it'), which cleanly separates it from the sibling `kick` (plain action) and `record_kick_distance` (manual fallback). An agent can identify it as a calibration experiment without opening the 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?

It gives a precondition ('Point the robot at open floor first') and an explicit alternative path when the normal flow fails ('If it rolls out of the camera's range... call record_kick_distance'). It does not, however, state when to prefer test_kick over the plain `kick` sibling, so the routing guidance is slightly incomplete.

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=false and destructiveHint=true, and the description usefully reinforces this by warning that the robot drives straight ahead and needs clear floor, implying collision risk. It does not explain blocking/time cost, what happens at the end of the run, or how return_to_start interacts with the physical motion. Adequate given annotations but adds only partial context.

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 experiment framing front-loaded and the physical constraint last. No filler, though the trailing clearance sentence fragments the flow slightly and could be folded into the first.

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 motion tool with no output schema, an agent is not told what results are returned (top speed figure? acceleration time? position) beyond the general intent, nor how long the robot is committed to the run. It covers the purpose and the main prerequisite, but leaves the outcome and timing behavior underspecified.

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 only 33%: distance_mm carries a description (oddly framed as clearance rather than a measurement), while speed_percent and return_to_start are undocumented. The description partly compensates by referencing the 'measured distance', the 'speed setting', and the clearance requirement, but return_to_start's behavior and units/ranges for speed are left to the schema alone.

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: drive a measured distance and time it to derive top speed and acceleration. This clearly differentiates it from the generic 'move' sibling, though it never names the contrast explicitly. An agent can tell this is a measurement experiment, not a locomotion command.

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 by the goal ('to find the robot's top speed at this speed setting'), so an agent can infer it is a benchmarking/characterization tool. However, there is no explicit when-not guidance or naming of alternatives such as move or test_kick for other measurement needs. The spatial prerequisite ('needs that much clear floor ahead') is the only hard usage constraint given.

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=false, destructiveHint=true, and openWorldHint=false. The description adds modest value by clarifying the motion is in-place ('on the spot') and self-terminating ('then stop'), but says nothing about speed defaults, motion range, or the meaning of the destructive 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?

Two tight sentences with the core action front-loaded and the usage hint following. Every clause earns its place with no redundancy.

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 2-parameter motion tool with full schema coverage and annotations covering the safety profile, the description is nearly complete. It would be fully complete if it clarified its relationship to turn_to_heading, its nearest sibling.

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 both degrees (sign convention) and speed_percent (deg/s) are fully documented in the schema. The description adds no parameter detail beyond it, making the baseline 3 appropriate.

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 ('Spin on the spot by an angle, then stop') that clearly conveys an in-place rotation. It references look() for a follow-up use, but does not differentiate itself from close siblings like turn_to_heading or face_object, which also change orientation.

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?

Provides one concrete usage context ('To face something seen in look(), turn by its bearing'), which is a helpful implied cue. However, it names no alternatives and gives no when-not guidance, so an agent has no basis to choose this over turn_to_heading or face_object.

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=false and destructiveHint=true, so the safety profile is covered by structured data. The description usefully adds that the motion is in place (no translation), but it does not say whether the call blocks until the turn completes, how collisions are handled, or whether motion must be enabled first.

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 nine-word sentence with no filler, and the distinguishing qualifiers are front-loaded immediately after the verb.

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?

Adequate but thin for a motion command: it omits blocking behavior, preconditions (enable_motion), and failure/collision semantics. No output schema exists, so the description carries the burden for return behavior and does not address 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?

Schema coverage is 100%: heading_deg already documents its zero reference and clockwise direction, and speed_percent documents its scale. The description adds nothing about parameter syntax, units, or the speed/heading interaction, so the baseline 3 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?

Specific verb+resource: 'spin on the spot to face an absolute heading'. The qualifiers 'on the spot' (rotation without translation) and 'absolute' (world-referenced rather than relative) implicitly separate it from siblings like turn and go_to, though no sibling is named.

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 only implied: 'absolute heading' suggests using this instead of a relative turn, and 'on the spot' suggests using it instead of go_to. There is no explicit when-to-use statement, no exclusion, and no mention of prerequisites such as enable_motion.

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 only cover the safety profile (readOnly, non-destructive, closed-world). The description adds real behavioral context beyond that: the ~10Hz polling rate, blocking semantics, that it returns bearings, and that it can time out. It stops short of stating the timeout default/max or what a timeout return looks like structurally.

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 core behavior and followed by the return semantics. Nothing is redundant and every clause carries information, including the polling rate and the two possible outcomes.

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 usefully covers return values (what happened with bearings, or a timeout). The main gap is that it doesn't explain how the event choice interacts with label/target (e.g. that 'seen'/'gone'/'close' need a target or label), which is a 4-param tool with a required event.

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 75%, with the event enum and timeout_s well documented in the schema itself. The description adds no parameter-level meaning, and 'target' has an enum but no schema description and is not clarified here. Baseline 3 is appropriate given the schema does most of the work.

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?

It names a specific behavior — watch the robot ~10x/second and return when an event fires — which is a concrete verb-plus-resource, not a tautology. It implicitly separates itself from polling siblings ('instead of checking over and over') but never names look/detect_objects/robot_status, so the differentiation is only suggestive.

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 phrase 'instead of checking over and over' implies this is the blocking alternative to repeated polling, which is useful implied guidance. However, it never states explicit when-to-use conditions, when-not to use it, or which sibling to prefer in a given situation.

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