Show, Don't Code

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

With no annotations at all, the description carries the full burden, and it does disclose meaningful behavior: each match includes the published volume, a verbatim quote that has been verified against the protocol text, both reagents' share, and a within-20% agreement verdict. It does not state that the operation is read-only, what happens when no kit match or no quote is found, how many matches are returned, or that an LLM (Muse Spark) reads the protocols, implying possible latency or cost.

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 a single dense, run-on sentence with a colon-delimited list, so the enumeration of match fields is not easy to scan. Every element is substantive, but the phrasing ("next to those of", "read by Muse Spark") front-loads awkwardly rather than stating the core action 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?

There is no output schema and no annotations, so the description must do all the work; it does a decent job describing the returned match structure and tolerance check, but leaves the sole parameter's meaning and the tool's usage context unexplained for what appears to be a non-trivial cross-referencing operation.

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 one required parameter, "name", with 0% description coverage, and the description never explains it. "This run's" weakly hints that the name identifies a run, but it could equally be a kit or protocol name; the description should have resolved this ambiguity since the schema 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 names a specific operation: comparing this run's per-reaction volumes against published protocols.io protocols using the same kit, and enumerating what each match contains. It is clearly not get_run, get_related_protocols or get_protocol, though it never explicitly says how it differs from get_related_protocols, which also deals with linked published protocols.

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, no prerequisites, and no mention of sibling tools. The agent must infer that this is a post-run validation step; the description is entirely about result content rather than invocation 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?

No annotations are provided, so the description carries the full behavioral burden. It gives rich context about what the card is (an edit of the real frame with no text drawn in, checked by Muse Spark to keep every object) and where image links live, but it never states whether calling this generates the card, whether it reads an already-generated one, or what happens if no card exists for a step.

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

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

The description is a single long sentence mixing the card's contents, the generation process, and the image URL structure. It is not padded with filler, but it is not front-loaded either: the URL mechanics arrive last and the most useful scoping fact is buried.

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 one required parameter, no annotations, and no output schema, the description needs to cover both what is returned and its shape. It tells us the card contains illustrations, a check, and reagent/volume data, and that image links follow a URL pattern, but leaves the return format, generation-vs-read behavior, and error cases 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?

The schema has a single undocumented parameter (0% description coverage), so the description must compensate. It partially does by showing the path pattern /api/runs/<name>/bench-card/<step>.jpg, which clarifies that 'name' is a run name, but it never says this directly and gives no format or validation details.

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

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

The verb-plus-resource ('get_bench_card' + bench card) is clear from the name and the description explains what the bench card contains (illustrated filmed steps, a check, reagent and volume). It is specific about the artifact but does not name the sibling tools or state explicitly that it returns the card rather than generating it.

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 guidance and no mention of alternatives such as get_tube_labels or get_receipt. The use case (training materials) is only implied by the description of content, so nothing helps an agent distinguish between this tool and related getters.

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

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

No annotations are provided, so the description carries the full behavioral burden, but it only characterizes the return artifact (Python, API 2.24, ready to import). It does not state that the operation is read-only, what happens if the name is unknown, or any permission/error behavior.

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

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

It is a single sentence with no filler, but it is under-specified rather than effectively concise; the sentence describes the return value and omits the action. Structure is not front-loaded with a purpose.

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 explained, yet the description spends its only sentence on the return artifact. For a one-parameter retrieval tool with no annotations, the definition lacks enough context to call it correctly or choose it over siblings.

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 sole required parameter 'name' has 0% schema description coverage, and the description never explains whether it is a protocol name, file name, or identifier. No meaning is added beyond 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?

The description is a noun phrase naming the output ('The generated Opentrons Flex protocol...') rather than a verb+resource statement. It adds format specificity (Python, API 2.24) but never says 'retrieve' and does not distinguish it from siblings like get_protocol_designer or get_related_protocols.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite close siblings get_protocol_designer and get_related_protocols. The agent is left to infer that this retrieves an existing generated protocol.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses the nature of the returned artifact (a Designer file, editable step-by-step, runnable as-is in the App), but says nothing about whether the call is read-only, whether it produces or mutates anything, or what happens when the name doesn't match a protocol.

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 what the caller receives and followed by the two actionable things to do with it. Nothing is padded, though the opening clause is slightly elliptical.

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 is the only source of truth about the return value, and it identifies the format but not how the file is delivered (path, base64, downloadable URL) or how large/complex it is. Combined with the undocumented 'name' parameter for a tool whose whole job is fetching an artifact, meaningful gaps remain.

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

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

There is a single required 'name' parameter with 0% schema description coverage, and the description adds no explicit meaning for it. However, for a one-parameter retrieval tool the surrounding sentences make the context clear enough that the gap is minor rather than blocking.

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

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

States the resource produced: 'The protocol as an Opentrons Protocol Designer file', which implicitly contrasts with the plain-protocol sibling get_protocol. The verb is only implied by the tool name ('get'), but the artifact and its format are 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 rather than stated: import it at designer.opentrons.com to edit without code, or run it in the Opentrons App. It never explicitly says when to pick this over get_protocol or which of the two to request for a given task, so the agent must infer the choice from the format difference.

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

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

With no annotations, the description carries the burden, and it does add real value by disclosing the returned fields and the dual-state nature of 'timestamp' (pending calendars vs confirming block). It says nothing about lookup failure behavior when no receipt exists, latency/external calendar dependence, or whether generation is triggered as a side effect.

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 sentence that front-loads the artifact definition and then qualifies the timestamp field. No filler, though the parenthetical is slightly compressed and the dangling list construction ("and which models ran, anchored in...") reads awkwardly.

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

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

For a one-parameter, no-output-schema tool the content summary is reasonably complete about what comes back, but the missing meaning of 'name' and the absence of any failure or availability semantics leave a real gap for an agent trying to call 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 coverage is 0% — the single required parameter 'name' has no description at all. The description never explains whether 'name' identifies a protocol, a run, or a receipt, so the one input the agent must supply is left ambiguous; the prose about hashes does not compensate.

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 specific resource (a reproducibility receipt) and enumerates its contents: SHA-256 of protocol/video/model outputs, which models ran, and Bitcoin/OpenTimestamps anchoring. That enough distinguishes it from siblings like get_protocol or get_run. It stops short of a 5 because it reads as a noun-phrase definition of the artifact rather than stating the action ('returns/fetches the receipt for a given run').

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

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

There is no when-to-use guidance, no prerequisites (e.g., a run must have completed), and no routing to siblings such as get_run or get_protocol for adjacent data. The agent must infer from the name alone when a receipt is the right artifact to fetch.

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

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

No annotations are supplied, so the description carries the burden. It does disclose the external source (public protocols.io content), that results include DOIs, and that it reports which reagent words each protocol mentions — genuine value beyond the name. It omits whether this is a live network call, how many results come back, and what happens when no matching protocol 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?

It is one sentence and front-loads the resource, which is good, but the trailing colon clause and the parenthetical '(brand and kit names)' make it read as a run-on. 'How other labs wrote up the same kit' is a worthwhile editorial framing; the DOI/reagent-word detail could be tightened.

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 it must describe returns, which it partially does (DOIs, mentioned reagent words). With no annotations and an undocumented parameter, it should say more about the identifier it accepts and the behavior of the external lookup. Adequate but with visible gaps for a tool that depends on an outside service.

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 parameter is only labeled 'Name', so the description must disambiguate it. The phrase 'this run's reagents' implies the argument identifies a run, but it never states whether 'name' is the run name, a reagent name, or a kit name — a real ambiguity for the one required input.

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: retrieves public protocols from protocols.io matched on this run's reagents (brand/kit names) and protocol type. That is distinguishable from siblings like get_protocol (a single known protocol) and get_protocol_designer. The phrasing 'with DOIs and which reagent words each mentions' muddies the core statement slightly, but the purpose remains identifiable 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?

The trailing clause 'how other labs wrote up the same kit' implies the use case (finding prior write-ups), but there is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. Usage is inferable rather than stated.

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

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

With no annotations or output schema, the description carries the full behavioral burden, and it only partially does so: it enumerates returned artifacts, which is genuinely useful, but says nothing about whether the run must already exist, what happens for an unknown name, or whether any computation/simulation is triggered server-side. The reading "get" implies read-only, but that is inference rather than disclosure.

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 sentence fragment with no redundancy, but it is not front-loaded: it opens with the most obscure item ("the steps found in the video") and buries the core purpose. A leading clause such as "Returns the analysis for a named run, including ..." would fix both the structure and the missing 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?

Because there is no output schema, the description must explain return values, and it does list the major content areas reasonably well. What is missing for a one-parameter retrieval tool is the identifier semantics and the lookup-failure behavior, plus any hint of how the run is selected relative to list_runs.

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

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

Schema coverage is 0% for the single required parameter `name`, and the description never mentions it — it does not clarify whether `name` is a run name, a protocol name, a video identifier, or a human-readable label. The description therefore does nothing to compensate for the schema 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 text is a noun phrase enumerating the payload contents (video steps with timestamps, open questions, simulator/protocol analysis, deck setup, runtime parameters, thermocycler minimum time) rather than a verb+resource statement. It conveys what a "run" record contains, but never says "retrieves the run record named X," so the agent must infer the action from the tool name 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?

There is no when-to-use guidance and no mention of the siblings that overlap most directly, such as list_runs (to find a run) or get_protocol/get_receipt. The agent is left to guess whether this is a lookup, an analysis trigger, or a bundle of derived artifacts.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the fill-volume computation (draw volume + 10% + dead volume), the reactions cap tied to protocol.py's max_reactions, and the concrete output artifacts (Avery L7160 SVG and Zebra ZPL 2x1 in). It stops short of stating permissions, error behavior, or whether the call is read-only, which is why it is not a 5.

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 leads with the core payload, which is good, but the main sentence is a long chain of parentheticals and mixed units that is harder to parse than necessary. The trailing sentence about printable label formats is useful but could be tightened; nothing is pure filler, though the structure is dense rather than front-loaded in a scannable way.

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 rightly spends most of its length explaining the return payload, including the label file formats. However, it omits the meaning of the required `name` argument and gives no indication of how many tubes or labels come back, so an agent still cannot fully predict the call contract.

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 parameters. It explains `reactions` well, tying it to the protocol's Reactions parameter and noting the max_reactions ceiling, but the required `name` parameter is never mentioned, leaving the agent to guess whether it expects a protocol name, run name, or label set identifier.

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

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

The description names a specific resource and enumerates exactly what it contains: per-tube deck slot and well, fill volume in µL, and the QR link. It clearly reads as a 'get the tube loading plan' tool, but never states the verb ('returns') and does not distinguish itself from siblings like get_bench_card or get_protocol, which likely also surface run setup information.

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 phrase 'before the run', which places it in the workflow ahead of execution. There is no explicit when-to-use/when-not-to-use statement and no pointer to an alternative tool if the agent wants the protocol or bench card instead.

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

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

No annotations are provided, so the description carries the full behavioral burden. It reveals only that names are returned and what a run is; it says nothing about ordering, whether results are scoped to a user/workspace, whether inactive or partially processed runs appear, or any access requirements.

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 very short with no filler, and the clarifying parenthetical earns its place. However, a bare noun fragment front-loads a return value rather than the action, leaving the reader to reconstruct 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?

An output schema exists, so return values need not be described, and the parenthetical covers the domain term. What remains missing for a zero-parameter listing tool is the most basic fact: that it lists, and under what scope.

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 and there is no parameter semantics for the description to compensate 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 phrase "Names of the sample runs" identifies the resource (sample runs) and hints at the return shape (names), and the parenthetical usefully defines a run as a video already turned into a protocol. But it is a noun fragment with no verb, so it never states the operation, and it does nothing to distinguish itself from the sibling get_run.

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

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

There is no when-to-use guidance at all. With get_run in the sibling list, an agent must infer that list_runs enumerates while get_run fetches one, and nothing in the description confirms or excludes any condition or alternative.

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

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

With no annotations, the description does substantial work: it discloses that execution is simulation-only, that it runs analysis, deck configuration and play, that it returns the robot's report (status, command count), and that it takes about a minute the first time and is then cached. It does not say whether running affects persisted run state (e.g., writes a receipt) or what happens on failure, which is the main remaining gap for a mutation-like 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?

Front-loaded with the core action and mode, and each subsequent sentence adds a distinct fact (return value, timing/caching, scope restriction). The middle clause ('the robot's analysis, deck configuration, play to the end') is a slightly listy restatement but still 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?

The description covers purpose, execution mode, return shape, cost and scope, which is good for a tool with no annotations and no output schema. However, with 0% schema description coverage and an undocumented required 'name' parameter, an agent still lacks what it needs to fill in the arguments 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 parameter meaning and largely does not. 'Reactions' is mentioned but never explained (units, allowed range, effect on the run), and the required 'name' parameter is never referenced at all — the reader has to guess it is the run identifier.

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 ('Run the run's protocol.py end to end on Opentrons' own robot-server') plus the execution mode ('in Flex simulation'), which is clearly distinct from siblings like get_protocol or get_run that only retrieve data. An agent can tell immediately that this is the execute/validate step.

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 context is clear (end-to-end validation in simulation before real execution), and it gives an explicit scope exclusion: 'Runs only the protocol this server generated, never code an agent sends.' It does not name sibling alternatives or state when not to run it (e.g., after the protocol is known to be stale), so it falls short of full when/when-not routing.

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