Contraptify

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered; the description adds value by disclosing what the call surfaces (coverage counts and unassigned blocks), which matters because there is no output schema. It stops short of describing ordering or exact return shape, but that is a minor gap given the annotation coverage.

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

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

Three short sentences, front-loaded with the return content, then the workflow cue, then the exclusion. Every sentence carries distinct information with no repetition of the title or schema.

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

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

With no output schema, the description adequately enumerates what comes back (parts, explanations, block counts, unassigned blocks) and situates the tool in the show/simulate workflow. Slightly more on the shape of the report would make it fully self-sufficient, but an agent can call it confidently as written.

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 `design` parameter with 100% schema description coverage, including detailed nested descriptions for blocks, parts, and tests. The description implies which sub-fields matter (`parts` and `blocks[].part`) but adds no format or structure detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb ("List") and a precise resource: a design's parts, their explanations, per-part block counts, and blocks lacking a part. This is clearly differentiated from siblings like show and simulate, so an agent can identify the tool 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?

Explicitly prescribes the workflow ("Use it before show to make sure every block is explained") and names the exclusion plus the correct alternative ("Do not use it to test whether the machine works: use simulate"). Both the when and the when-not are stated with the sibling to use 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 declare readOnly, idempotent, closed-world and non-destructive, so safety is covered; the description instead adds genuinely new behavioral context: the response is large and size scales with design complexity (2,500 vs 5,100 blocks). It stops short of saying whether such large payloads are truncated or paginated, which is the one piece of behavior an agent calling a read tool with 5,100-block responses would want.

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

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

Three sentences, front-loaded with what is returned, then a size caveat, then the exclusion. Every sentence earns its place and nothing is repeated from the schema or annotations.

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

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

With no output schema and no parameter descriptions, the description compensates by enumerating the return contents, warning about payload size with concrete magnitudes, and routing the display use case elsewhere. An agent has everything needed to decide and call correctly.

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

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

Schema coverage is 0% for the single `id` parameter, so the description must carry the meaning — and it does, identifying the id as coming 'from list_examples'. It does not state the id's format or whether an unknown id errors versus returns empty, leaving a small 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?

Specific verb ('Return') plus a precisely scoped resource ('one built-in example design') and an explicit payload listing (blocks, part explanations, its own test). It also names where the id comes from (list_examples) and separates itself from show, so an agent can distinguish it from all three relevant siblings without opening a schema.

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

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

Explicit negative guidance — 'Do not use it to show an example to the user: use show with example set' — names the alternative and the condition that selects it. The id source ('from list_examples') closes the remaining workflow question of how to obtain the required parameter.

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, idempotent, non-destructive, and closed-world, so the safety profile needs no restating. The description adds useful content-level context (the catalogue is small and fixed, with concrete examples) and routes block retrieval elsewhere. It does not say whether results are names, ids, or objects, which is the one behavioral gap.

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

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

Three short sentences with zero waste: purpose, then the concrete contents, then usage and the redirect. 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 should hint at what comes back; naming the example designs partially does that, and the get_example redirect is the critical missing piece an agent would otherwise get wrong. Minor gap: unclear whether the list returns names, ids, or descriptions to feed into get_example.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly says nothing about parameters rather than padding.

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

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

States a specific verb and resource ("List the built-in example designs") and immediately enumerates the actual contents (clocks, counters, piston door, lock, flying machine), so the agent knows exactly what domain objects come back. It explicitly distinguishes itself from the sibling get_example.

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 the positive case ("Use it to find a known-good starting point") and an explicit exclusion with the alternative named ("Do not use it to fetch a design's blocks: use get_example"). The when/when-not/alternative triad is fully present.

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

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

Annotations already declare this a safe read-only, idempotent, non-destructive operation, and the description adds real behavioral context the annotations don't cover: the output is an interactive in-chat viewer with per-part click text, and the requirement to simulate first. It stops short of saying what happens when the design is invalid or how the viewer behaves on re-invocation, so not a full 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?

Three sentences, front-loaded with what the user sees, then input sourcing, then the prerequisite and the exclusion. Every clause carries distinct information with no restatement of the name or title.

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

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

For a complex nested-input tool with no output schema, the description covers purpose, interaction model, input sourcing, and the simulate-first dependency, which is enough to call it correctly. Minor gaps remain around failure modes for an invalid design and whether the viewer is persistent.

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

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

Schema coverage is 100%, so 3 is the floor, and the description earns above that by clarifying the exclusive-or relationship between the two optional parameters and by sourcing example ids from list_examples, neither of which the schema states. It doesn't add anything about the nested design fields, which the schema already documents in depth.

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?

A specific verb ('show') plus resource ('a design ... in an interactive 3D viewer in the chat'), with the rendering behavior spelled out (buttons, levers, tick-by-tick, orbit, click-to-explain). It explicitly names the sibling it is not ('Do not use it to test a design: use simulate'), so an agent can separate it from simulate without reading schemas.

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

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

Gives the two input paths ('Give either design, or example'), where example ids come from (list_examples), a precondition ('Simulate the design first'), and an explicit exclusion routed to an alternative tool. Nothing about when-to-use is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds substantial behavior beyond that: the exact categories of output (failing expectations with actual values and timing, visible changes, dispenser shots, breakage notes) and what happens when the optional test is omitted. It stops short of stating runtime limits or cost, but that is minor for a sandbox simulation.

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, then the output contract, then the sibling routing rule — a sensible order. The output enumeration is dense but every clause names a distinct result category; the only mild bloat is listing example visible-change types.

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

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

No output schema exists, so the description must carry the return contract, and it does in concrete terms. Combined with a deep nested input schema, an agent has everything needed to decide when to call it and how to interpret results.

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

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

Schema description coverage is 100% and the nested 'test' object is thoroughly documented, so the schema does the heavy lifting. The description still adds value the schema does not: it frames 'test' as optional and explains that omitting it produces a plain run-and-report, which clarifies the default behavior of the only parameter.

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 a redstone design with its own test') plus the exact result shape: which expectations hold, what visibly changed, dispenser shots, and breakage notes. It explicitly separates itself from the sibling 'show', so an agent can choose between them without opening schemas.

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

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

Gives both a positive rule ('Use it on every candidate before showing it') and an explicit exclusion with the alternative named ('Do not use it to display a design to the user: use show'). It also covers the no-test fallback case, so no usage mode is left to inference.

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