Picodev Lab

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

Annotations already cover the safety profile (non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavior: sampling cadence ("one every 2 seconds"), the t_ms reference point (ms since start of turn), and the null-when-unknown convention. It does not clarify whether a call captures a new frame or returns the most recent one, nor what agent_token authorizes.

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 compact sentences with every clause carrying information and the cadence/timing detail front-loaded. The opening is a dangling modifier with no main verb, which costs a little structural clarity, but there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does a decent job describing the return (image plus t_ms), but it omits the input contract entirely for a two-parameter tool and never connects to session lifecycle siblings (open_session, session_status, close_session). An agent could call it but could not confidently reason about the session/token arguments.

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 carries the full burden — and it mentions neither 'session' nor 'agent_token'. The critical question of what happens when session is null (default) is left unanswered, so the agent gets no help on inputs 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 describes the artifact ("a photo of the bench, as an image") and the timing field, which lets an agent infer this tool retrieves a bench camera snapshot. But there is no verb naming the action — no "capture" or "return" — and no differentiation from sibling capture tools like capture_analog, capture_logic, or read_capture. An agent must infer the operation from the title and noun phrase.

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 says the tool applies "during the session's turn on a real bench," which hints at context, but gives no explicit when-to-use versus capture_analog/capture_logic/read_capture, and no preconditions (does a session need to be open via open_session?). No 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?

The description discloses important side effects beyond the annotations: send=true emails Picodev, send=false sends nothing, nda=true suppresses the PDF, and the PDF is written on the visitor’s machine. It also explains consent requirements, privacy retention, and the exact consent text to show, which is valuable behavioral context not covered by 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?

The key action and send/preview distinction are front-loaded, and most of the dense detail is necessary for this complex tool. The description is long and heavily semicolon-driven, but the consent text and conditional rules earn their 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?

For a 10-parameter tool with no output schema, the description provides the return shape, conditional behavior for nda and preview, consent prerequisites, section constraints, and PDF-writing side effects. It is complete enough for an agent to invoke the tool safely and 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?

With 0% schema description coverage across 10 parameters, the description compensates substantially: it explains sections, send, consent, contact fields, nda, session, agent_token, language, and the figures relationship to spec_draft. It still leaves some details implicit, such as the full Figure object shape and the role of title, so it is strong but not exhaustive.

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: sending the visitor’s project specification to Picodev as a PDF, or returning a preview when send=false. It also distinguishes this tool from the sibling spec_draft by instructing the agent to write sections with spec_draft first.

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 explicitly states when to use preview versus send, the prerequisites for send=true (contact and consent), how nda=true changes behavior, and the required consent confirmation workflow. It names spec_draft as the prerequisite drafting tool, giving the agent clear 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?

Beyond the minimal annotations, the description discloses key behavior: simulation-only refusal on a real bench, how ADC vs non-ADC pins are interpreted, PWM appearing as a square wave, the default scope-probe pins, and the 200,000-sample cap. These are substantive operational constraints an agent needs before invoking the tool.

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

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

The description is front-loaded with the core action and key parameters, then adds behavioral and simulation constraints efficiently. Despite being a dense paragraph, every clause contributes hardware-specific or operational meaning.

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 5-parameter capture tool with no output schema, the description provides enough to call it correctly and retrieve results via read_capture. However, it leaves session and agent_token unexplained and does not clarify what the capture result reference looks like.

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 does well for pins, rate_hz, and duration_ms with ranges and pin mappings, but it never explains session or agent_token, and it only partially covers defaults for rate and duration.

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: 'Sample the voltage of 1 to 4 board pins' at a given rate and duration. It clearly separates analog ADC readings from non-ADC pins whose logic level is sampled, and tells the agent to read the result with read_capture.

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 usage context by specifying analog voltage sampling, pin count, rate/duration ranges, and the simulation-only restriction. It also names read_capture as the follow-up tool, but it does not explicitly say to use capture_logic for digital captures, leaving that sibling relationship implicit.

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?

Adds substantial context beyond the annotations: the real-time-vs-simulated-time distinction, the fact that no browser or running simulation is needed on a bench, and the hard 10 000 ms ceiling on total recording length. Annotations only say readOnly=false and destructive=false; the description explains the timing/blocking implications the annotations cannot.

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 and duration are front-loaded, and every sentence carries technical content rather than filler. The trigger clause is dense and slightly run-on, so density costs a little readability, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a seven-parameter tool with no output schema and only coarse annotations, the description covers execution context, timing semantics, trigger logic, and follow-up tools. Only the session/agent_token parameters and return-shape expectations are left implicit, and those are standard session plumbing.

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 the load, and it does for the important parameters: duration_ms range (1–10 000), the trigger object's pin/edge with the edge enum values (rising, falling, any), and how pre_ms/wait_ms interact. It leaves session and agent_token unexplained, which is the only significant gap across seven parameters.

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

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

States a specific verb and resource ('Record every edge of the requested pins ... for duration_ms') and clarifies the default pin set ('by default the logic ones'), so the agent knows exactly what is captured. It does not contrast itself with the sibling capture_analog, which is the one nearby tool an agent could confuse it with, so it falls short of a 5.

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

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

Explicitly names the downstream tools ('Read the result with read_capture, decode it with decode_capture'), which routes the agent correctly after the call. It also explains the two execution contexts (browser simulation vs real bench), giving clear conditions under which it behaves differently. No explicit exclusion against capture_analog.

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, and the description goes beyond them by spelling out the consequences: the place/turn ends, viewers and the browser are disconnected, and state is forgotten. That is genuine impact disclosure for an irreversible action, though it says nothing about the agent_token authorization needed to perform 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?

A single tight sentence that front-loads the action and then enumerates the effects. Nothing is wasted and the ordering is optimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, no-output tool the description covers the consequences well, but with 0% schema coverage on two parameters and no hint about authorization or default session targeting, an agent still lacks the information needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for both 'session' and 'agent_token' — and it does not mention either. An agent cannot tell from the description whether omitting them closes the current session or which session is targeted.

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

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

The description uses a specific verb and resource ('End the session now') and distinguishes it implicitly from open_session/session_status by framing it as the terminal action. It doesn't explicitly name a sibling, but the action is unmistakable.

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

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

'End the session now, as when it expires' implies the trigger (deliberate early termination equivalent to natural expiry), but gives no explicit when-to-use vs. staying in the session, and no mention of queue_leave or other cleanup siblings that an agent might confuse with closing the session.

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 readOnly/non-destructive/closed-world, and the description adds real behavior beyond them: per-protocol option defaults and ranges, a 2000-frame pagination limit via offset, error flags on UART frames, and a 'problems' field for doubtful decoding. It omits auth/session prerequisites, which is the remaining gap.

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

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

Purpose is front-loaded in the first clause, and nearly every clause carries payload. But it is a dense run-on of semicolon-separated fragments with inline JSON-ish notation that is hard to scan for a fast-moving agent.

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 compensates by documenting the return envelope and per-protocol frame shapes (t_us, value, error, cs-low framing, i2c start/restart/ack). The missing pieces are session/agent_token semantics and confirmation of the capture identifier format.

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 so well: it enumerates every channel pin set per protocol, the full options vocabulary with defaults (baud 9600, bits 8, parity none, mode 0, bit_order), and explains offset through the 2000-frame window. It never explains 'session' or 'agent_token', leaving two of seven params 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 ('Decode a ready logic capture of the session') plus scope (browser or bench). It does not name the sibling it differs from (read_capture, capture_logic), so the agent must infer which one produces vs consumes a capture.

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 'ready ... capture' implies a precondition, but the description never says when to use this versus read_capture or capture_logic, nor what to do if decoding fails or the capture isn't ready. Usage is only implied.

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

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

Annotations already declare this a safe read (readOnlyHint true, destructiveHint false, closed-world), so the description is not burdened with the safety profile. It adds genuine domain semantics beyond annotations: what 'available' vs 'soon' means operationally (soon setups cannot be opened), and that a 'soon' bench is simply not offered yet. It says nothing about ordering, pagination or auth, but the closed-world/read annotations plus the output schema cover most of that.

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 with no filler; every clause defines a distinct field of the returned setups. The front-loading is weak because it opens with the bare noun phrase 'The setups:' rather than a verb, and the nested parentheticals make it slightly harder to parse than necessary.

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?

This is a zero-arg, read-only, closed-world list operation with an output schema, so return structure need not be re-explained. The description supplies exactly what structured fields cannot: the meaning of the status/mode/bench vocabularies the agent will encounter in the response and the consequence that 'soon' entries are not actionable.

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 no parameter semantics to explain and the baseline of 4 applies. The description's enum-like vocabulary (available/soon, free/challenge, open/soon) is useful for interpreting the response but is not parameter guidance.

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

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

The description makes clear the resource is the catalog of setups and enumerates the attributes returned: status (available/soon), modes (free/challenge) and benches by kind. It does not distinguish this from the sibling read_setup (single-setup read) or bench_snapshot, and it uses a noun fragment ('The setups:') rather than an explicit verb, but the content of the listing 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 only implied: the parenthetical '(open_session works)' hints that available setups are the ones you can proceed to open, and 'cannot be opened yet' sets a boundary. There is no explicit statement of when to call this versus read_setup, nor a prerequisite/first-step recommendation, leaving the agent to infer the discovery-then-open flow.

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?

Beyond the annotations, the description discloses that this mutates challenge state, returns {level, levels}, and causes session_status's level to change. It does not describe error behavior when the precondition is not met, but it adds meaningful behavioral context that the annotations do not cover.

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

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

The description is front-loaded with the action and condition, and every clause carries useful information. The semicolon-heavy phrasing is a bit dense, but there is little wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a state-changing challenge action, it explains the trigger condition, return shape, and side effect on session_status. However, with no output schema and no parameter descriptions, it omits how to supply session or agent_token and does not cover failure behavior, leaving notable 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?

The schema has two parameters ('session' and 'agent_token') with 0% description coverage, and the description does not mention either parameter. It fails to compensate for the schema gap, leaving an agent with no guidance on how these inputs affect the call.

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 action ('move to the next level') and ties it to challenge mode and the bench's Next level button. It is clearly distinguishable from siblings in intent, though it does not explicitly name alternative 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?

It gives a precise condition for use: only when every test of the current level passed and a next level exists. It also says 'No level skipping,' which clarifies a negative constraint, but it does not name alternative tools or spell out what to do when the condition is not met.

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 this is not read-only and not destructive, so the key safety profile is covered. The description adds important behavior beyond annotations: the session is human-gated and simulation does not start until the human opens the returned URL. It does not cover permissions or session lifetime.

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, front-loaded with the action and mode, followed by the critical human handoff instruction. There is no wasted wording.

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 mentions open_url and the human-gated simulation behavior. However, it omits any explanation of the required setup parameter and does not clarify the session lifecycle, leaving notable gaps for an agent invoking the 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 partially documents mode by naming 'free or challenge', but the required setup parameter is left completely unexplained.

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: 'Create a session', and adds the mode distinction '(mode: free or challenge)'. It is distinguishable from siblings like close_session and session_status by the creation action and the human browser handoff, though it does not explicitly name alternatives.

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

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

It gives clear operational context: create the session, then give open_url to the human because nothing simulates until they open it. It does not discuss when not to use this tool or name alternative session tools, 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?

Goes well past the annotations: it discloses that the running simulation stops, that the payload is validated against component types and pins, that the outcome must be read back via read_simulation (circuit, circuit_error), and that the call is rate limited to 6 per minute. It also caps the payload at 40 components, 120 wires and 48 KiB, which is exactly the operational envelope an agent needs.

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?

Dense but well front-loaded: the mode gate and the destructive-ish side effect ('the simulation stops') come first, then structure, then limits. The mid-sentence 'in the shape of the setup sheet's circuit' is a soft reference that adds little and interrupts the flow.

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 an output schema present, the description doesn't need to explain return values, and it correctly redirects to read_simulation for the validation result. It's nearly complete; the gap is the two optional auth/session parameters and any hint about whether a session must be open first.

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 schema types components/wires as bare objects, so the description carries the entire burden — and it does, spelling out {type, id, properties, x?, y?}, the wire shape with start/end/color/waypoints, the 16-waypoint cap, and the caveat that the board is not a component. The session and agent_token parameters get no mention at all, which keeps it off a 5.

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: replace the circuit in the human's browser, and explicitly ties it to Free mode, which is a strong scope statement. It does not, however, distinguish itself from the similarly named push_program or push_to_editor siblings, so an agent must infer that 'circuit' versus 'program' is the dividing line.

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?

'Free mode only' is an explicit precondition and a de facto when-not rule, which is more than most tools offer. No alternative tool is named for the non-free-mode case (e.g. push_to_editor), so the routing guidance is incomplete at the boundary.

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 (not read-only, non-destructive, closed-world); the description adds what they cannot: the 48 KiB ceiling, that the hex is loaded without recompiling, that the sim auto-starts when run=true, and that 'during a turn on a real bench, the bench gets it too' — a genuine side effect worth flagging. It omits any auth/session expectations, which is the only 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?

Front-loaded with the core action and constraints; each sentence carries information (format, size, files semantics, bench behavior, sibling preference). The 'bench gets it too' clause is terse to the point of ambiguity but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations covering safety, the description covers format, limits, side effects, and routing. The remaining gap is the two undocumented optional parameters (session, agent_token) for a 5-parameter 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 explains hex (Intel HEX text, size limit, arduino-cli example) and files (sources, read-only in editor, never compiled), and implies run's effect ('if run, starts it'), but says nothing about session or agent_token — two of five parameters left unexplained.

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 ('send a program compiled on the visitor's machine ... to the human's browser') plus format (Intel HEX), size cap (48 KiB), and runtime effect (loads in simulator without compiling, starts if run). It is clearly separable from push_to_editor and push_circuit.

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 recommends itself over a named sibling: 'Prefer it to push_to_editor, which is the fallback when the local toolchain is missing.' That gives both the preferred case and the alternative's condition.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond them - it overwrites the human's editor buffer, may compile in the lab's cloud, and may start execution. It leaves the default of `run=true` and the meaning of the session/token fields implicit, and does not flag that replacing browser code discards prior content.

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 primary action and closed with the routing rule, with no filler. Every clause conveys either what it does or when to pick it.

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?

An output schema exists, so return values need not be described, and the routing guidance is solid. But with four parameters at 0% schema coverage and mutation semantics, the description is thin on the mechanics of the `files`, `session`, and `agent_token` inputs.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only hints at `run` ('if run') and says nothing about the `files` array shape, `session`, or `agent_token`. An agent cannot infer from the description what a session identifier means or when to supply the token.

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 - 'Replace the code in the human's browser' - and then names the sibling push_program as the default, positioning itself as the fallback. An agent can distinguish it from push_program and push_circuit without opening any schema.

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

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

Gives an explicit conditional: 'use it only when the toolchain to compile locally is missing (no arduino-cli, core or library)'. Both the when and the when-not are stated, along with the alternative that should be preferred otherwise.

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 this is a non-read-only, non-destructive, closed-world mutation, so the safety profile is already covered. The description adds the useful prerequisite that the browser must be connected, but omits the most important behavior for a queue-join: whether the call blocks until a bench is granted, returns immediately with a position, or fails when the queue is full.

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, front-loaded with the action and followed by the precondition; nothing is redundant. It is not padded, though it is arguably too terse given the undocumented parameters.

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 mutation with no output schema and no annotation detail beyond hints, the definition leaves critical gaps: return behavior (position? token? blocking?), meaning of session and agent_token, and error conditions. The completeness bar is higher than what these two sentences deliver.

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 the parameter burden and it does not. 'Kind' is only illustrated obliquely ('real or sim') with no list of accepted values, and the optional 'session' and 'agent_token' parameters are never mentioned at all — an agent cannot tell when to supply them.

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 (join) and resource (bench queue), scoped by 'of this kind' with the 'real or sim' example clarifying what kind means. It is clearly distinguishable from queue_leave and queue_status by name and action, though it never names 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?

The prerequisite 'the browser must be connected' gives one concrete condition for calling it, which is more than most. But there is no guidance on when to join versus checking queue_status first, when to prefer queue_leave, or what to do if already queued — usage is implied rather than stated.

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

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

Annotations already declare a non-destructive, closed-world mutation, so the safety profile is covered. The description adds genuine behavioral value by disclosing the two possible outcomes (returning a queued place vs. relinquishing an in-progress turn), but says nothing about error behavior, whether the call is idempotent, or what identity is needed to leave.

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 twelve-word sentence with zero filler, and the primary outcome is front-loaded. It is arguably too terse for a mutation with two undocumented optional parameters, but there is no wasted prose to trim.

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 state-changing tool with no output schema, no annotations covering outcome semantics, and two parameters at 0% schema coverage, the description should say what a successful leave returns or confirms and what identity is required. The one-line description is not enough to call this confidently without trial and error.

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 neither `session` nor `agent_token` is documented anywhere. With both parameters optional and unexplained, an agent cannot tell whether omitting them infers identity from context or fails silently — the description must compensate here and does not mention parameters 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 action on a specific resource: relinquishing a position in the bench queue, and clarifies it also covers an already-started turn. The verb is colloquial ("give back the place") but the meaning is unambiguous against siblings queue_join and queue_status, which the name already separates.

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 by the verb — call it when you want out of the queue. There is no statement about what happens if the caller is not queued (error vs no-op), no mention of queue_join as the inverse path, and no prerequisites such as when a session must be open. Adequate but leaves the agent to infer.

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

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

Annotations already establish that this is a read-only, non-destructive, non-open-world operation. Beyond that, the description adds useful behavioral detail by enumerating the possible returned states and some associated fields such as position, eta_s, bench, and ends_at in Unix seconds.

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 definition is a single compact sentence with no wasted prose, and it front-loads the core concept of the session's queue place. The parenthetical state breakdown is efficient, though the phrasing is dense and could be slightly clearer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does a reasonable job of explaining the possible return states and key fields. However, for a tool with two undocumented optional parameters, it leaves important invocation details unresolved, so the definition is only adequate rather than complete.

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 explain the two optional parameters, but it does not meaningfully describe either session or agent_token. The word 'session' hints at the session parameter, but there is no explanation of defaults, whether omission means the current session, or what agent_token is for.

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

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

The description clearly identifies the resource: the session's place in a queue, with possible states none, waiting, or turn. It is understandable without opening the schema, but it does not explicitly differentiate this status tool from siblings such as queue_join, queue_leave, or session_status.

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

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

Usage is only implied: an agent can infer this tool is for checking a session's current queue position or turn state. There is no explicit when-to-use guidance, no exclusions, and no mention of when to prefer queue_join, queue_leave, or session_status 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 already cover read-only/non-destructive/closed-world, and the description goes well beyond them: pagination of 2000 items from offset, the null-terminated `next` cursor, t0_ms clock semantics (simulation launch vs. turn start on a real bench), state-dependent payload availability, and a real rate limit (4 chart requests per minute). It stops short of saying what happens if you read a capture that is still recording (error vs. state-only response).

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 dense block with no filler sentences; state/kind is front-loaded before the conditional payload descriptions. Every clause carries information (units, array layouts, cursor semantics), though the run-on grammar makes it hard to parse on first read.

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 fully carries the return contract: field names, units (t_us, mv, rate_hz), row ordering relative to pins, and cursor behavior are all spelled out. The remaining gap is error/lifecycle behavior when the capture is not ready and the meaning of the session/agent_token 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 description coverage is 0%, so the description carries the burden: it explains offset (2000 items per page), format="png", and from_ms/to_ms (measured from capture start, used to zoom). It says nothing about `capture`, `session`, or `agent_token`, leaving three of seven parameters completely unexplained 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?

The description names the resource precisely (a capture) and enumerates what it returns: state (recording/ready/failed), kind (logic/analog), per-pin measures, and either edges or samples. It is specific enough to distinguish this as the read/fetch companion to capture_logic/capture_analog, but it never states that distinction explicitly or contrasts with decode_capture.

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: the polling loop is hinted at by 'Once ready...' plus 'next: the following offset, or null', and format="png" is offered as a chart alternative to raw data. There is no explicit 'use this when...' guidance and no sibling named as an alternative for any case.

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 this as a safe, read-only, closed-world operation. The description adds meaningful behavioral context beyond annotations: it states the setup is never a solution, that levels are returned without hints, where hints are exposed, and that schema.png is included only when it exists.

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 definition is a single front-loaded sentence that packs in all relevant content details without wasted sentences. It is somewhat dense and parenthetical, but every clause adds useful information about what is returned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with annotations covering safety and no output schema, the description is largely complete: it explains the returned content and the important exception around hints and optional images. The main remaining gap is the unexplained 'id' 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?

Schema description coverage is 0% and the single required parameter is only named 'id'. The description never clarifies that this is a setup identifier, what form it takes, or where to find it. With low schema coverage, the description should compensate, but it does not.

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

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

The description clearly identifies the resource as a served setup sheet and enumerates its contents (board, components, wires, probes, levels, schema.png), so the agent knows what it returns. However, it opens with a noun phrase rather than a verb and does not explicitly differentiate this tool from list_setups or other setup-related siblings.

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

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

Usage is implied: read a setup sheet to obtain its circuit and levels. The description helpfully notes that hints are not included and come through read_simulation instead, but it gives no explicit guidance on when to choose this tool over list_setups or how to obtain the required setup id.

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 read-only, non-destructive, closed-world profile, and the description adds substantial context beyond them: serial is capped at 16 KiB and reset at each compile, events are capped at 2000, circuit_error is 'returned once', circuit_modified is null when unknown. It does not cover pagination or cost of repeated polls, but the behavioral disclosure is unusually rich for a read tool.

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

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

No sentence is pure filler — each one describes a distinct returned field or constraint — but there is no front-loaded summary sentence; the text starts with a parenthetical and reads as a dense, unterminated field dump, making it hard to scan for the one routing rule it contains.

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 justifiably spends most of its length documenting return values, and it does so thoroughly (bench mode, challenge mode, circuit_modified, circuit_error). But it leaves the auth-ish `agent_token` unexplained and never positions the tool against its many siblings, so it is not fully complete for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry all three parameters. It handles since_ms well (events window, 2000 cap) but says nothing about `session` or `agent_token`, the latter of which looks like an auth/identity parameter that materially affects invocation.

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 never states a clean verb+resource; it opens mid-thought with 'Last state (with circuit, the browser's components and wires), last compilation and the events after since_ms' — effectively a catalogue of returned fields. An agent can infer this reads simulation state, but nothing distinguishes it from siblings like bench_snapshot, read_capture or session_status.

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

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

One explicit preference is given: 'prefer it over reconstructing serial from `events`', which is a genuine routing rule. The since_ms window ('2000 at most') implies polling usage, but there is no guidance on when to choose this over bench_snapshot or read_capture, and no prerequisites 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 only tell the agent it is a non-read-only, non-destructive, open-world call. The description goes well beyond: it triggers an e-mail to a third party, states the data retention period (3 years), links the privacy policy, spells out the exact consent wording that must be displayed, and describes the confirmation flow ('Picodev answers by e-mail to confirm a slot'). That is exactly the disclosure an agent needs for an externally-visible operation.

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

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

It is front-loaded with the action and every sentence carries information; the two consent texts are long but are verbatim content the agent must reproduce, so they earn their space. The downside is that everything is delivered as one undifferentiated paragraph, and the session/agent_token clause is muddled rather than 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 no output schema, the description still explains the return shape ({sent, next}) and the downstream process (e-mail confirmation of a slot). Combining that with the consent workflow, availability constraints and retention disclosure, an agent has everything needed to call this 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 coverage is 0%, so the description carries the full burden and mostly succeeds: it explains contact sub-fields, the 2000-character cap on context, the two availabilities shapes ({from,to} ISO 8601 with time zone within 60 days, or a single {text} sentence) and the 1-10 slot limit. The one weak spot is 'session and agent_token, optional: the mail also says what the visitor did in the lab', which is grammatically garbled and never explains what those two values actually are.

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 first sentence states a specific verb and resource: 'Send Picodev a meeting request.' No sibling tool in the list (capture_logic, open_session, queue_join, etc.) overlaps with it, so an agent can distinguish it immediately from the surrounding lab toolset.

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 concrete operational conditions: consent=true is required, the visitor must be shown the consent text in their language and must accept before consent is passed, and availabilities must fall within 60 days with 1-10 slots. What's missing is a positive statement of the intent trigger (e.g. 'use when the visitor wants to book time with the Picodev team'), though with no competing sibling that gap is minor.

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?

Beyond the readOnly/non-destructive annotations, the description discloses genuinely useful traits: it is cheap to poll, it does NOT write to the human's journal, and fetching the viewer link does not renew it. The 'event times restart at each run' note clarifies counter semantics. What's missing is any note on error behavior for an invalid/expired session.

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 key distinctions ('without its events', 'cheap enough to poll') are front-loaded in the first clause. The long parenthetical field enumeration is dense but earns its place because there is no output schema, though scannability suffers in a single run-on sentence.

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?

Return fields are covered thoroughly, which is necessary given no output schema. However, with 0% parameter coverage the definition omits how to target a session at all, which is a meaningful gap for a two-parameter 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% and both parameters (session, agent_token) are completely undocumented in the schema. The description never explains what 'session' defaults to or what agent_token is for, so an agent has no guidance on whether it must supply them.

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

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

The description clearly identifies the resource (the session's state) and its defining characteristic: it returns state 'without its events', separating it from event-reading siblings. It never names an alternative tool, so the agent must infer the boundary from sibling names alone.

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?

'Cheap enough to poll' is the only usage cue and it does imply a polling/monitoring role. There is no explicit when-not guidance and no sibling (e.g. queue_status, bench_snapshot, read_simulation) is named as an alternative, leaving selection 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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds genuinely valuable behavior beyond them: it returns the viewer link and that current viewers are disconnected when visibility changes. The disconnect side effect is not captured by destructiveHint=false, though it is a session-level disruption rather than data destruction, so this is added context rather than a contradiction.

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 compact sentences: the operation first, then the observable return and side effect. No filler, and the most decision-relevant information 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?

With no output schema, the description helpfully names the return value (viewer link) and the disconnect consequence, which is the main completeness win. However, for a mutation tool it omits auth/permission expectations and leaves the session and agent_token parameters unexplained, so an agent still guesses at invocation details.

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 there are no enums, so the description must carry the parameter burden. It partially compensates by listing the accepted visibility values (private, link, public), but says nothing about the 'session' and 'agent_token' parameters, leaving two of three undocumented anywhere.

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 ('Change') and resource ('visibility') and enumerates the allowed values (private, link, public), so an agent knows exactly what the tool does. No sibling is named, but none of the siblings (session, capture, bench, queue tools) overlap meaningfully, so differentiation is less critical.

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 never says when to use this tool, what preconditions exist (e.g. an open session, ownership, auth), or how it relates to any alternative. The only implied guidance is the enumeration of visibility values, which is 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?

Adds substantial context beyond the readOnly/openWorld/destructive annotations: 'Nothing is sent and nothing is kept' (privacy posture), per-section 4000-character cap, 1000-character contact cap, max 3 figures at 200 KiB decoded, and explicit SVG sandboxing rules ('no script, no DTD, href # or data:image/ only'). These are real constraints an agent could not infer 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 content is largely necessary given zero schema coverage and no output schema, and it is front-loaded with the purpose first. However the prose is dense run-on semicolon splicing with heavy parenthetical nesting, making parameters and return values hard to scan; a short structured list would have served better.

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 fully spells out the return object: rules, sections array with id/heading/required/state/look_for/questions, next, ready semantics ('the four required sections filled'), filename and base64 pdf. An agent has everything needed to drive the interview loop 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 0%, so the description must carry the full burden and it does: all five parameters are explained with semantics, limits and defaults — sections ids enumerated (envelope, fonctionPrincipale, fonctions, alimentation, format, environnement, production, preferences), contact carved out as non-progress, language limited to fr/en with what it affects, and pdf=true requiring title, plus figure object shape.

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 artifact: 'Draft the specification of the visitor's own project with Picodev's interview', and explains the mechanism (you ask the visitor, the tool says what to ask next and makes the PDF). No sibling tool in the list performs spec drafting, so there is no ambiguity to resolve.

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

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

Gives concrete calling guidance: 'Call it with the sections written so far (none at first)' and 'Returns {rules ... follow them}', which establishes the iterative interview loop. It does not name any alternative or exclusion condition, but no sibling overlaps in purpose, so the missing piece is minor.

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?

The annotations already establish non-destructive, non-open-world, non-read-only behavior. Beyond that, the description adds a real behavioral constraint (at most one answer per second), says the hub checks the answer and returns {test, ok}, and notes that the verdict also appears in the bench. Auth requirements for `agent_token` and what happens on a failed check are not covered.

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

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

The description is front-loaded with the challenge-mode scope and the core action, and it is compact. The hint sentence is peripheral, but it earns its place by routing the agent away from using this tool to obtain a hint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description explains the return payload ({test, ok}), and the annotations cover the safety profile. Still, for a four-parameter action tool with 0% schema coverage, the description omits both auth/session parameters and any failure or error behavior, so it is only adequate rather than complete.

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 the full burden for all four parameters. It explains `test` (an answer test of the level's brief) and `value` (the proposed answer), but it says nothing about `session` or `agent_token`, which are authentication/session parameters that an agent needs to understand in order to call the tool correctly.

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

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

The description states a specific verb and resource: it proposes `value` as the answer to the current level's `test`, and it scopes this to challenge mode. It does not explicitly differentiate itself from the sibling `brief_submit`, so the reader must infer the distinction from the word 'answer' and the context of the level's test.

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 an implied context ('Challenge mode') and a rate limit, and it redirects hint-seeking to the bench rather than this tool. It does not name a competing sibling such as `brief_submit` or say when this tool should not be used instead of the bench, leaving the choice only partly guided.

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