Tomorrow Lives Engines

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

Annotations already cover read-only/idempotent/non-destructive/closed-world, and the description adds genuinely new behavior: no rendering occurs, it returns 'ok' or exactly one sentence naming the first problem and its location, and it consumes no units. That cost/side-effect disclosure is exactly the kind of context annotations cannot express.

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

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

A single sentence with a colon-delimited result spec; the most decision-relevant fact (no rendering, no cost) is front-loaded and every clause earns its place.

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

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

With a rich output schema and fully documented annotations, the description only needs to add cost and validation semantics, which it does. It could be slightly stronger by noting where a valid design document comes from (e.g. art_starter/art_schema), but nothing needed to invoke it correctly is missing.

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

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

There is one parameter and schema coverage is 100%, with the schema itself pointing to art_schema for the document keys. The description adds nothing about the 'design' argument, so the baseline 3 for high schema coverage applies.

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

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

States a specific verb (checks) and resource (a design), and immediately delimits scope with 'without rendering it', which cleanly separates it from art_render and the other *render siblings. An agent can tell what this does and what it does not do 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?

'Costs no units' gives a clear economic reason to call this before art_render, which is an implied when-to-use cue. It stops short of naming art_render explicitly or stating exclusions, so it is clear context rather than a full routing rule.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds that this is the shipped library, that it is free ('Costs no units'), and that returned ids are usable for layer fill or baking, which is useful context beyond the structured fields.

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

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

Three short sentences front-load what the resource is, then add usage and cost details without repetition. No sentence 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 no-parameter listing tool with an output schema and full read-only annotations, the description supplies the essential framing—what the library contains and that it is free. Nothing needed to call it correctly is missing.

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

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

With zero input parameters, the baseline is 4; there is no parameter information to add beyond the empty 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?

Names the resource (the shipped material library) and its per-entry contents (id, look line, metal flag), so an agent knows it is a listing tool. It does not explicitly name a sibling alternative, but the content framing differentiates it from mutation tools like material_apply or material_bake.

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?

Says any id can fill a layer or be baked and that it costs no units, which tells the agent when to use it (to obtain material ids) and a cost constraint. It stops short of naming alternatives such as material_check or material_cost and gives no explicit when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds genuinely new context beyond annotations with 'Costs no units', which matters in a toolset that includes multiple *_cost siblings, though it says nothing about caching or output format.

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

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

A single sentence, front-loaded with the resource and its enumeration, with the billing note last. It is tight, though the full inline listing of preset values partially duplicates what the output schema already returns.

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 does not need to explain return values, and with zero parameters the schema burden is minimal. The description supplies the domain context (presets exist for shirts, stickers, posters) that makes the tool selectable, leaving only explicit sibling routing as a gap.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter surface for the description to clarify, and the enumerated preset names serve as the implicit enumeration of valid future inputs.

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 concrete resource (canvas presets) and enumerates exactly which presets exist with their pixel dimensions and DPI, so an agent immediately knows what it will get back. It does not explicitly differentiate itself from siblings such as art_schema or art_materials, which is the only thing keeping it from a 5.

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

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

Usage is implied rather than stated: an agent can infer this is the lookup to call before choosing a canvas size for rendering. There is no explicit when-to-use, no when-not-to-use, and no named alternative among the art_* siblings.

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

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

Annotations only declare the safety profile (not read-only, not idempotent, non-destructive), so the description earns credit for disclosing the cost model (1 unit at <=1200px, 5 units wider), the default canvas size (4500x5400 shirt front), and the returned signed URLs. It does not say whether rendering is synchronous or job-backed, which would matter given the sibling job/cancel_job tools.

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?

Four dense sentences, front-loaded with the core action and the default-size behavior, with no filler. The closing sentence about return artifacts is slightly redundant given an output schema exists, which keeps it from a perfect score.

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

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

For a 4-parameter tool with a nested design document and an output schema, the description covers sizing, cost, preview behaviour, and output artifacts. The remaining gap is the rendering lifecycle (sync vs async, how it relates to the job tools) and any prerequisite that the design be validated 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 100%, so baseline is 3, and the description adds meaning beyond the schema: the concrete 4500x5400 full-print canvas, the 1200-pixel cost boundary, and the fact that preview_on paints the shirt colour behind a transparent design. This is genuine added value rather than restatement.

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 ('Renders a design to a PNG') and adds the distinguishing detail that DPI is written in. It is immediately clear what artifact comes out, though it never contrasts itself with near-name siblings like raster_render or video_render, so an agent must infer which renderer applies.

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 explains the width-omitted vs width-supplied behavior, which is useful operational guidance, but that guidance is really about a parameter rather than about when to choose this tool over alternatives. No when-not conditions or named alternative tools appear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds a genuinely non-obvious behavioral fact — "Costs no units" — which is billing/quota context an agent cannot get from the annotations or schema. It does not describe response shape, but an output schema exists to carry 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?

Three short sentences, front-loaded with what the tool is, then when to call it, then the cost note. No filler and nothing 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?

For a zero-parameter schema-discovery tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what it returns conceptually, when to call it, and that it is free. Only the absence of sibling routing keeps it from a 5.

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

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

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. No parameter guidance is needed and none is missing.

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 resource — the complete vocabulary (keys, ranges, words) a print design may use — which is a real capability statement rather than a restatement of the title. It is distinguishable from the sibling *_schema tools by domain (print vs raster/video/world) and from art_render/art_check by being a reference lookup, though it never explicitly names those 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?

"Call this first when designing a print" gives explicit ordering guidance relative to the rest of the art_* workflow. It does not name an alternative or state when not to call it, 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.

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds the cost-free behavior ('Costs no units'), which is valuable and not in annotations. It does not mention auth or rate limits.

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

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

Two short sentences, front-loaded with the resource and the cost caveat, with no filler.

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

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

For a simple read-only starter with an output schema and rich annotations, the description covers purpose and cost. The only gap is sibling routing, but overall it is complete enough.

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% and the enum fully describes the single preset parameter. The description adds no parameter detail beyond what the schema provides, so baseline 3 applies.

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

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

States it provides a valid starting design for a canvas preset and that it is ready to edit. It is a specific resource but does not name a sibling to distinguish from art_presets or art_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?

Implies use when starting a design and wanting no cost, but no explicit when-to-use versus art_presets or art_schema, and no exclusions or prerequisites.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses a real side effect the annotations only imply: a credit cost that scales with size (1 unit at <=512, 2 units above). It also states the output format. No annotation contradiction — a unit-consuming render is consistent with readOnlyHint=false.

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 dense sentences: the first defines the operation and output, the second states the size range, default, and cost tiers. Nothing is redundant and the core identity 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?

An output schema exists, so return-value details are unnecessary. Inputs, cost model, and artifact type are covered. The main remaining gap is that nothing explains the readOnlyHint=false beyond cost — e.g., whether a job is queued or credits are only reserved on failure.

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

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

Schema coverage is 100%, so the 3 baseline applies. The description still adds quantitative meaning the schema only gestures at ('Above 512 costs more') by giving the exact tier split (1 unit vs. 2 units), and restates the size bounds/default alongside that consequence.

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 ('Renders one material ... as a lit square swatch PNG'), and the output artifact type (square swatch PNG) implicitly separates it from raster_render, art_render, and material_bake. It does not explicitly name which sibling to use instead, so it stops short of full sibling differentiation.

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 clarifies the two accepted forms of the material argument (shipped id vs. inline material document) and routes discovery to art_materials for ids, which is useful context. However, it gives no when-to-use/when-not guidance relative to the other rendering tools in the family, leaving selection largely 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?

Goes well beyond the annotations: annotations only say mutation/destructive/idempotent, while the description explains the billing model (free if still waiting, charged for CPU used if running, one unit per 10 CPU-seconds rounded up, capped at the job's price), states the tool itself costs nothing, and states what the response contains. This is exactly the extra context annotations cannot carry.

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 action and its scope, then immediately the state-dependent cost rules in parallel clauses, then the response. Three sentences, no filler, each carrying distinct information.

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

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

An output schema exists and annotations cover the safety profile, so the remaining burden is applicability and cost behavior — both fully addressed. An agent can call this correctly and predict the charge from the description alone.

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% for the single required `job` parameter, including the job_ + 24-hex-digits format, so the schema already does the work. The description adds no syntax or sourcing detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (cancel) and resource (queued job), then bounds the scope by enumerating the job types it applies to (video_still, video_render, raster_render, large pull_analyse/pull_twin/pull_lab). That enumeration separates it from sibling inspection/mutation tools like job, jobs, and pull_close 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?

Makes applicability explicit by naming job types, and distinguishes the two runtime states (waiting vs running) with the consequence of each. It does not name an alternative tool or an explicit 'do not use this when...' exclusion, so it stops just short of a 5.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the description carries most of the burden and does well: it discloses cost (3 units near, 1 unit mid/far), determinism ("the same seed and options return the same one"), glb buffer savings, and loop behavior of animation clips. It does not disclose whether a job is queued asynchronously or how the result is delivered.

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 ~500-word run-on block with comma-spliced clauses ("as makes the seed a foe, a machine...", "age young, adult or old takes the first seed from seed on whose person the town rolls...") that is very hard to scan. The purpose statement is front-loaded, but the useful option guidance is buried mid-paragraph rather than organized by parameter.

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 13-parameter, no-required-param generator, the description is substantively complete: outputs, formats, clip sets, costs and determinism are all covered, and an output schema exists so return values need not be restated. The main gap is process-level behavior (sync vs job-based execution), which is not addressed.

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

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

Schema description coverage is 100%, so the baseline is 3, but the prose adds real meaning the schema lacks: which clip names exist and their loop lengths/speeds, that glb replaces gltf when both are requested, that clip travel distance equals a cycle at the gait's speed, and that travel clips walk on the spot by default. Some of this duplicates the schema, but the net addition is above baseline.

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?

Opens with a specific verb+resource ("Generates a character from a seed") and the rest of the text makes the scope concrete: procedural townspeople/animals, posed meshes plus looping gait clips. It distinguishes itself indirectly by pointing at character_list as the source of gait names, but it never plainly states what character_generate does that nearby tools (character_list, art_presets) do not.

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

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

Usage is implied by scattered conditionals ("clips asks instead for a set of named looping clips... for a character controller", "travel true also carries the root forward"), which tell an agent which options to reach for. There is no explicit when-to-use-this-tool vs alternative, no prerequisites, and no statement about when not to call it.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds one genuinely new behavioral fact not present in annotations — 'Costs no units' — which is useful for a units-metered system. It does not, however, discuss caching, output shape, or rate 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?

Two compact sentences with the payload enumerated up front and the cost caveat appended. Every clause carries information; only the fragmentary, verb-less phrasing slightly weakens the structure.

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-value documentation is unnecessary, and the description still previews the returned data (kinds, detail levels, gaits). Given a parameterless read-only tool, this is close to sufficient; only a pointer to how the result relates to character_generate is missing.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline is 4. No parameter confusion is possible.

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

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

The description enumerates exactly what the tool surfaces — body kinds (person, dog, cat, rat, sheep), levels of detail, and each kind's gaits — so the resource and payload are unambiguous. It lacks an explicit verb ('list'), but the noun enumeration makes the read intent clear enough to distinguish it from the sibling character_generate.

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

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

There is no guidance on when to call this versus character_generate or any other sibling. The only hint is the incidental 'Costs no units,' which is a cost note rather than a selection rationale.

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

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

Annotations only give a generic safety profile (readOnlyHint=false, destructiveHint=false), yet the description discloses determinism ('The same seed and size give the same city'), the cost model ('Costs 1 unit; views add to it'), what each output file contains, and how terrain/relief alters geometry (terracing, stepped buildings, retaining walls, apron). This is far beyond what the annotations convey.

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

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

The content is dense but delivered as one enormous run-on block riddled with nested parentheticals, so it is neither front-loaded beyond the first clause nor scannable. Much of the detail (every park/bench/hedge rule) is over-specified for a tool-selection decision and would be better in documentation.

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 9-parameter procedural generator with an output schema, the description is thorough enough that an agent could invoke it correctly, including cost and determinism caveats. It is slightly redundant in re-describing return values already covered by the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: default formats ('json, png and glb by default'), the content of each file type, what terrain/relief/origin do geometrically, and the camera meanings behind view. It stops short of explaining every parameter interaction, so not 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?

The opening clause states a specific verb and resource — 'Makes a city from a seed number and a size' — and then enumerates exactly what the output contains (streets, blocks, lots, buildings, terrain). An agent can tell this is a procedural city generator distinct from terrain_heightmap, raster_render or world_apply 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?

Usage is only implied. The description explains what view is 'for when there is no model viewer to open them in' and cross-references terrain_heightmap for terrain seed words, but never states when to choose city_plan over a sibling generator or what the prerequisites are. No explicit when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower, and the description still adds two genuinely non-redundant facts: the batch is atomic (all-or-nothing) and the call costs 1 unit. It stops short of mentioning permissions or failure/rollback 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?

One tight sentence that front-loads the action, then the op vocabulary, then the atomicity guarantee and cost. Nothing is wasted and no sentence is padding.

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, and atomicity plus cost are disclosed. However, the description never says where the inline 'form' document comes from (form_build/form_starter or a fetch), which is the main practical uncertainty for invoking a mutation tool that takes the whole document inline.

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

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

Schema description coverage is 100%, so both 'ops' and 'form' are already documented in the schema, including the same op-name list and the whole-or-not-at-all note. The description adds no syntax, format, or constraint detail (e.g. the 200-item cap) beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb (applies a batch of ops) and resource (a form document), and enumerates the exact op names, so the agent knows this is the mutation entry point for forms. It does not explicitly distinguish itself from siblings such as form_build or form_check, leaving that differentiation to 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 versus when-not-to-use guidance and no alternative tool is named, even though form_build, form_check, and form_starter sit right next to it. The 'whole or not at all' clause describes atomicity, not when this tool should be selected.

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 the safety profile (readOnly=false, destructive=false, openWorld=false, idempotent=false), so the bar is lower. The description adds genuinely non-structured context: a per-call cost of 1 unit and the determinism guarantee that the same variant always builds the same shape, which reconciles with the non-idempotent hint by implying repeated calls re-spend units. It stops short of stating permissions or failure modes.

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

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

Dense and front-loaded: the verb, accepted form kinds, and reported output come first, with the lod vocabulary and cost tacked on as short clauses. No filler sentences, though the return-value sentence is somewhat heavy given an output schema exists.

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 need not explain return values, yet it does anyway; that redundancy is harmless. It covers cost, accepted form inputs and lod values, leaving only sibling differentiation and auth/prerequisite behavior unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents form, variant and lod. The description's additions (example ids 'scots-pine, oak, boulder', the lod enumeration, the determinism note) largely duplicate schema text already present, so this stays at the baseline 3.

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 ('Builds a form ... at one variant') and describes the observable result (knob values, vertex/triangle counts per LOD). It does not, however, differentiate itself from nearby siblings such as form_apply, form_check or form_starter, so an agent must infer the boundary from 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?

Usage is only implied: you call it to build/realize a form and inspect its geometry. There is no explicit when-to-use, when-not-to-use, or named alternative despite three form_* siblings existing. The 'Costs 1 unit' note is a useful decision input but not 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds a behavioral detail not present in the annotations – that the operation 'Costs no units' – plus the fact that validation runs against a 'strict reader'. It doesn't say what happens on failure, but an output schema exists to carry results.

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, with no redundant or filler text. Every clause carries information.

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

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

For a one-parameter validator with a present output schema and full annotation coverage, the description supplies the essentials (what is checked, what it is checked against, and that it is free). The only gap is that 'the sculptor's strict reader' is left undefined, so the agent does not know what rules are enforced.

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 a single parameter and 100% schema description coverage, the schema already documents the 'form' object including that it is written inline as JSON. The description adds no format, size, or content constraints beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Checks a form document') and names the validation target ('the sculptor's strict reader'), which distinguishes it from the sibling form_build/form_apply mutation tools. However, it never explicitly contrasts itself with the other *_check siblings (art_check, video_check, etc.) or with form_apply, so sibling differentiation is only implied.

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

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

Usage is implied by the check/apply naming pattern, and 'Costs no units' is a useful hint that it is a free operation. But the description gives no explicit when-to-use guidance, no statement of what the strict reader rejects, and no pointer to form_apply for the mutation path.

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, non-destructive and closed-world, so the safety profile is covered. The description adds one real behavioral fact not present in structured data, that the call costs no units, but says nothing about whether the named form persists or what the returned document contains.

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 no filler; the artifact and its enumeration come first and the cost note is appended. Nothing is padded, though the kind list duplicates data the schema already holds.

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-value explanation is not needed, and the annotations plus 100%-covered schema carry the safety and parameter burden for a low-complexity two-parameter tool. The only shortfall is the missing placement guidance relative to the other form_* tools.

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 both parameters carry clear descriptions including the id pattern and the kind list, so the baseline of 3 applies. The description restates the kind enumeration already in the schema and adds no new syntax or constraint 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 description names the concrete artifact produced (a blank form document), scopes it to a generator kind, and enumerates every valid kind, so the resource is unambiguous. It omits the verb (returns? creates?) and does not distinguish itself from siblings like form_build, form_apply or form_check, which is exactly the gap between a 4 and a 5.

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

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

There is no statement of when to reach for this tool versus form_build, form_apply or form_check, nor any prerequisite such as a required prior step in a flow. The only contextual hint, 'costs no units', is a cost note rather than usage guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond that: the full status lifecycle (queued/running/ok/refused/failed/cancelled/expired), that wait_s blocks until completion, that a completed pull job's report is report.json, and that it is free.

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 what the tool returns, then the status/wait semantics, then cost. It is dense but every sentence carries information; the parenthetical lists of job types and statuses are the only slight bulk.

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, return values need not be enumerated, yet the description still explains status values, wait semantics, and the key file (report.json). For a 2-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, establishing a baseline of 3. The description only restates wait_s's blocking behavior and max of 25, which the schema already says ('Seconds to hold the answer until the job ends'), so it adds little beyond the structured fields.

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 (read) and resource (a job's status) plus the payload it returns (files as signed URLs, small PNGs inline). It clearly scopes to a single job, distinguishing it in effect from the list-style sibling 'jobs' and the mutation sibling 'cancel_job', though it never names those alternatives explicitly.

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

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

It gives the operating context for a queued job, explains the polling pattern via wait_s (at most 25, holds until the job ends), and notes 'Costs nothing'. It does not explicitly route to alternatives (jobs for listing, cancel_job for cancellation), so it stops just short of full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts beyond them: a hard cap of 50 results, that only ids and states are returned (not full payloads), newest-first ordering, and that the call costs nothing. It does not define what the state values are, which would have made it 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?

Three short sentences, each earning its place: scope and ordering first, the sibling pointer second, the cost note last. No repetition of the title and 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 an output schema present, return-field documentation is not required, and annotations carry the safety profile, so the description only needs to add cap, ordering, subset, cost and the sibling relationship — all of which it does. The one gap is that 'queued' states are not enumerated, leaving the agent to infer what state values it will see.

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 of 4 applies. The description correctly adds no parameter detail and instead spends its words on result shape and cost, which is the right allocation.

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) plus resource (jobs) with precise scope: this account's newest queued jobs, at most 50, ids and states only, newest first. It also explicitly separates itself from the sibling 'job' tool, which reads one in full, so an agent can route without opening either 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?

Names the alternative ('The job tool reads one in full'), which strongly implies the workflow: use jobs to discover ids, then job to read details. It stops short of an explicit when-not or a statement that non-queued/historical jobs are excluded, so it is clear context but not a full routing rule.

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 only declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the description carries the extra burden well: it states the atomic all-or-nothing batch semantics, that it returns either the edited document or the refusal, and that it costs 1 unit. It does not describe what triggers a refusal or how large batches are limited (500 ops), which keeps it from 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 is a single dense sentence, and the ordering is good: verb, target, op vocabulary, atomicity contract, return value, then cost. The 14-item op enumeration is long but each name is genuinely useful to a calling agent, so it earns its length.

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, return structure need not be restated, and the annotations cover safety; the description still adds the atomicity contract and cost. The main residual gap is failure semantics — what a 'refusal' looks like and why one occurs — which matters for a mutating tool with a 500-op ceiling.

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 already 100%, so the baseline is 3; the description adds value by listing all fourteen op names (the schema only lists a representative subset plus 'and the rest') and by stressing that ops apply in order within the atomic batch. The inline-JSON nature of the material document parameter is left to the schema.

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

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

The title-plus-description names a specific verb ('applies a batch of ops') and resource ('a material document') and enumerates the exact operation set, so the agent knows precisely what capability this exposes. It never names a sibling (e.g. material_check or material_bake) to distinguish itself, so it stops short of a 5.

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

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

Usage is only implied: an agent infers it should call this when it needs to mutate a material, and the 'Costs 1 unit' note is a useful budgeting hint. There is no explicit when-to-use vs. material_check/material_cost guidance and no stated prerequisites, so it is minimum-viable rather than strong.

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 generic profile (not read-only, not idempotent, not destructive), so the description carries the real burden and does disclose meaningful behavior: the produced artifacts, the fixed set of channels, and a cost model (1 unit at 512 or below, 2 units at 1024). What is still missing is where the PNGs land and whether rebaking overwrites prior output.

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 tightly packed sentences with zero filler: the operation and its outputs come first, then the resolution/cost tradeoff. Every clause earns its place.

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

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

With an output schema present, return values need no explanation, and the description covers the operation, output channels, resolution range, and cost. It leaves minor gaps around output destination and interaction with existing baked assets, but nothing that would block a correct call.

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

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

Schema description coverage is 100%, so both parameters are already documented structurally. The description restates the resolution options and cost and clarifies that 'material' can be a shipped id or an inline document, but adds no syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Bakes a material') and enumerates the exact output artifacts (seven named channels as PNGs). It is easy to tell apart from material_apply or material_check in practice, but it never explicitly contrasts itself with those siblings, so it stops short of a 5.

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

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

There is no statement of when to use this tool versus alternatives such as material_apply, material_cost, or material_check, nor any prerequisites (e.g., must the material already exist or be validated). The cost-per-resolution note is useful for choosing an argument, but it 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: it is free ('costs no units') and returns a binary admissible/refusal verdict against a strict reader, which is not captured in the structured fields.

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

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

Two tight clauses with the verb front-loaded and zero filler; the cost note follows the outcome statement and earns its place by informing invocation decisions.

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 the verdict format need not be explained, and annotations carry the safety profile. Combined with the cost and strictness notes, an agent has enough to invoke it correctly, though the meaning of 'strict reader' remains slightly opaque.

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 a single parameter at 100% schema coverage, the schema already documents that the material is an inline JSON object. The description adds nothing about the expected document shape or constraints, so the baseline 3 applies.

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

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

States a specific verb (checks) plus resource (material document) and the outcome form ('admissible, or the refusal'). It is clearly distinguishable from write siblings like material_apply or material_bake, though it never names them explicitly. The 'engine's strict reader' phrasing is somewhat internal jargon.

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?

'Costs no units' implicitly signals this is a free pre-flight validation you can call before material_apply, which is useful implied guidance. However, it never states when-not to use it or explicitly contrasts it with material_cost or material_apply.

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, and non-destructive. The description adds information the annotations do not carry: that the call consumes no credits ('Costs no units'), which is a genuine billing/side-effect clarification beyond the structured safety hints.

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

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

A single compact sentence front-loads the cost question and then the return units. The trailing 'Costs no units.' is terse but earns its place by clarifying billing, so the structure is efficient without waste.

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 the description need not document the returned operations/bytes structure. Combined with 100% schema coverage for inputs, the only real gap is the absence of an explicit pointer to material_bake as the follow-up action.

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 both parameters are already documented there, including the res default of 256. The description repeats the res default but adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific verb+resource ('what baking a material document costs') and states the return shape ('operations and bytes'). It distinguishes itself implicitly from the sibling material_bake by being a pricing query rather than the bake itself, though it never names that sibling explicitly.

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

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

Usage is only implied: an agent can infer this is a pre-flight estimate for material_bake, but the description never says when to call it instead of material_bake or material_check. No prerequisites or exclusions are given.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true, and the description substantiates this by spelling out that the write path is 'name, change, or resend' rather than destruction. It goes well beyond the structured fields by disclosing the email-masking behavior ('address hidden in the middle'), the full set of read states, the confirmation/plan lifecycle, and that the call costs nothing.

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?

Four compact sentences, front-loaded with what the resource is before splitting into read/write modes. Every clause carries information (states, masking, plan trigger). Minor debt: 'a pass never waits for it' and 'Costs nothing' are terser than they are clarifying, but nothing is filler.

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

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

An output schema exists, so return shape need not be explained, yet the description still summarizes the possible read states. For a single-optional-parameter tool with annotations covering the safety profile, an agent has all it needs to invoke correctly. Only the jargon-y confirmation/pass interaction leaves a small interpretive gap.

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

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

Schema coverage is 100% and the single parameter is already documented, so the baseline is 3. The description adds semantics the schema does not: the same parameter can name the owner, change an existing value, or merely re-send a confirmation, and that omitting it is a read. That is real meaning beyond the schema's terse 'omit it to read'.

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

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

Names a specific resource (the account owner) and precisely describes its dual behavior: a no-argument read versus an owner_email write/resend. It even enumerates the states the read returns (confirmed, unconfirmed, missing, removed), which most definitions omit. It is clear enough to distinguish from any sibling, though the phrasing 'by email' and the opening fragment make the first sentence slightly oblique.

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

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

Explicitly states the selection condition between the two modes: no arguments reads state, owner_email names/changes/resends. No alternative tools are named, but none of the siblings overlap with owner management, so there is nothing to route away from. Prerequisite context (free plan starts on confirmation) is also given.

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

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

Annotations give readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false, but the description adds real value: it explains the algorithmic basis (offset and uncertainty from the fastest round trip), discloses the side effect that a two-station session is recorded (which is why readOnlyHint is false), and states the cost ('Costs 1 unit'). That is meaningfully more than the annotations provide.

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 the action front-loaded, which is good, but the trailing clause 'and the stations record a two-station session carries' is awkward to the point of ambiguity about what is actually recorded. The core content earns its place; the phrasing does not.

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 tool with a full schema and an output schema, most needs are covered: the description supplies the algorithm, the clock-domain semantics of the ping triple, the session side effect, and cost. Given annotations and schema carry the rest, little is missing beyond sibling routing.

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 there is a single parameter, so the schema already documents the [sent_ns, remote_ns, received_ns] triple. The description restates the same semantics, adding only the parenthetical that sent/received use this station's clock and remote the other's — marginal beyond the schema. Baseline 3 applies.

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

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

Names a specific verb+resource ('Aligns two stations' clocks') and goes on to describe the ping input and the estimated offset, making the action identifiable. However, it never distinguishes itself from any of the many pull_* siblings (pull_analyse, pull_twin, pull_replay), so an agent has no anchor for when this is the right pull tool. The final clause about the session is garbled and blurs the purpose somewhat.

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 the required input shape but no when-to-use guidance, no prerequisites, and no comparison to the sibling pull_* tools that likely overlap. An agent must infer usage entirely from the mechanics. Only the implicit framing ('from repeated pings') hints at context.

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

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

Annotations mark it as non-read-only, non-idempotent, non-destructive, open-world false. The description adds substantial behavioral detail: cost model (40000 draws per unit), queuing threshold>2 units, 202/402 plan limits, and that sessions are not kept. This goes well beyond annotations. However, it doesn't clarify auth requirements or rate limits beyond the cost model.

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, extremely long and dense paragraph with minimal structure. It is not front-loaded; key information about cost and queuing is buried in the middle. While concise in word count, it is hard to parse due to lack of organization.

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?

Given the complexity (8 parameters, output schema exists, nested logic), the description covers most behavioral aspects: cost, queuing, plan limits, and data retention. It might miss some edge cases but is fairly complete for an advanced tool.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds some context about parameter behavior (e.g., surrogates range, measure default), but baselines at 3 when schema does the heavy lifting.

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

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

The description states a specific verb and resource: it analyses sessions of one condition and returns a detailed report. It is clear what the tool does, but it does not explicitly differentiate itself from siblings like pull_replay or pull_prereg, which likely also deal with session analysis.

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 mentions related tools (prereg registers, replication analyses a second set), implying usage contexts, but it does not give explicit when-to-use vs. when-not-to-use guidance or name alternatives for this specific analysis task.

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 the non-destructive/non-idempotent profile, and the description usefully adds latency ('Answers at once, within 30 seconds'), cost ('Costs 1 unit'), and the constraint that no flags pass through. However, for a generic verb dispatcher whose read/write behavior depends on the named verb, the description never addresses whether the invoked verb can mutate state, leaving the biggest behavioral unknown uncovered.

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 and the exclusion list plus latency/cost details are packed in efficiently. The phrasing is slightly ornate ('the way to reach what the engine adds before this service lists it'), which costs a little clarity but not much space.

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, return values need no explaining, and the description covers routing, exclusions, latency, and cost. The only real gap is the unstated mutation semantics of the underlying verb, which matters for a generic dispatcher.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including the verb name pattern and the optional 'document'. The description reinforces that only one document is passed and that no flags are accepted, but adds little syntactic meaning beyond the structured fields. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Runs an ae_pull verb ... by its name, over one document') and explicitly differentiates itself from the sibling pull_* tools by listing the verbs it refuses. An agent can tell immediately what this does and when it differs from pull_schema, pull_cost, etc.

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 sides of the routing rule: use this for verbs 'this list does not name yet', and do NOT use it for schema, analyse, twin, schedule, seal, open, prereg, replay, close, align, lab, cost, or practice, each of which has its own call. Explicit when/when-not with named alternatives.

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

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

Annotations cover the safety profile (non-read-only, non-idempotent, non-destructive), and the description adds genuinely new context: the session is returned with a closed record hash and recomputed hashes, and the call 'Costs 1 unit'. That mutation/cost detail goes beyond the annotations, though it omits reversibility.

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 clauses that front-load the action and its effect. The phrasing ('the session back with its closed record hash') is slightly awkward but wastes little space.

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, return values need not be re-explained, and annotations carry the safety profile, so the description is largely sufficient. Its gap is sibling differentiation: nothing tells an agent how this differs from pull_seal or pull_open, which matters in a family this crowded.

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

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

Schema coverage is 100%, so both parameters are already documented, including the exact 'at or after the session's end' constraint that the description repeats. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Closes a session's files') with a clear scoping constraint. However, it does not distinguish this from the many related session tools (pull_open, pull_seal, pull_replay), so an agent cannot tell from the description alone when closing beats sealing.

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 a precondition ('at or after its end_ns') that implicitly bounds valid usage, but it names no alternatives and gives no explicit when-to-use/when-not guidance against sibling tools like pull_seal or pull_open.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: 'Runs and renders nothing. Costs no units.' plus the refusal semantics and the note that a queued call's price is the engine count. This is genuine added value that the annotations cannot express.

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 first clause is well front-loaded, but the body is a dense run-on with nested parentheticals and repetitive 'price/priced' wording that is hard to parse. The length is partly justified by 13 parameters and three input modes, yet the structure could be much cleaner.

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 13-parameter, multi-mode tool with nested objects, the description covers the key facts an agent needs: what is and isn't run, that it costs no units, and the meaning of the answer (for/units/queued/within_limits) even though an output schema exists. It falls just short of complete because mode-selection and refusal conditions are stated obliquely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a semantic grouping the flat schema lacks: it explains which parameter clusters belong to the twin mode (twin, condition, coupling, planted, field, sessions, seed) versus the analysis mode (prereg, replication, surrogates, pairs) versus the lab mode (theory, reference). That mode-mapping meaningfully helps an agent pick the right arguments.

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

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

The opening clause 'Prices a call without making it' gives a specific verb and resource and states the key scope (a dry-run cost estimate). It goes on to name the sibling tools whose arguments it accepts (pull_twin, pull_analyse, pull_lab), which helps distinguish it. However the phrasing is so convoluted that the crisp differentiator against pull_call is buried rather than front-and-center.

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: you feed it the arguments of pull_twin/pull_analyse/pull_lab to learn what a call would cost, and 'nothing at all is the default twin' gives a fallback. It also names an exclusion (the one-dimensional references 'are refused here by name'). But there is no explicit when-to-use-this-instead-of-calling guidance.

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

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

Annotations only assert readOnlyHint=false, idempotentHint=false, openWorldHint=false, destructiveHint=false; the description adds substantial disclosure beyond that: async 202 responses with a job id, the GET /api/agents/jobs/<job> (or 'job' tool) completion path, 402 refusal on the free plan, paid-plan requirement for queued jobs, thread counts, CPU-time estimation rules, and explicit refusal conditions (lattice narrower than the soliton, unsettled relaxations stopped at 3x estimate). This is exactly the operational context an agent needs before invoking.

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 body is a single enormous run-on paragraph that buries the selection-relevant facts under extreme numeric minutiae (64,001 sites, ~3,200 CPU-seconds, 0.05 spacing, 16 box, 25-to-43 step counts). Only the first clause is front-loaded; the rest is unordered and hard to scan, and much of the cost arithmetic is not actionable at call time.

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-parameter tool with an output schema present, the description covers the essentials an agent needs: queuing threshold, plan gating, refusal modes, timeouts, and the failure/pricing contract. Return-value detail is legitimately offloaded to the output schema, though the density makes it hard to confirm coverage at a glance.

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% and both parameters are documented in-schema, so the baseline is 3. The description goes further by characterizing the inline theory document (fields, Lagrangian, which quantity is the mass, what fixes the sector and the expected value) and by spelling out reference semantics (true = the one-dimensional suite; reference skyrme/hopfion select model-based runs), which the schema's const/pattern does not convey.

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

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

States a concrete verb+resource: "Runs the pull engine's field-theory lab on a theory document", and the opening clause enumerates what the lab produces (equations derived, static solution weighed, oscillation and collision). That is well beyond a tautology of the title. It does not, however, explicitly distinguish itself from close siblings such as pull_call, pull_analyse or pull_practice, so an agent must infer the boundary.

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 conditional routing details (reference=true runs the reference suite, >2-unit calls are queued, free-plan queued calls return 402) and defers key discovery to pull_schema and pricing to pull_cost. But it never says when to reach for pull_lab rather than pull_call/pull_analyse; usage is implied by the cost/queue mechanics rather than stated as a selection rule.

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 substantial behavior: the failure path returns 200 with ok false, intact false and a reason (rather than erroring), nothing is persisted ('Nothing is kept'), and the call costs 1 unit even for a broken seal. Cost and statelessness are exactly the kind of context annotations do not convey. The one soft tension is 'Nothing is kept' against readOnlyHint=false, but the 'Costs 1 unit' billing mutation reconciles 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?

The action is front-loaded and the three sentences are information-dense with little waste. The first sentence is heavy with nested parentheticals and a JSON fragment, which slightly hurts readability, but nothing is redundant.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile; the description still goes further by documenting the failure response, cost, and statelessness. The only omission is any reference to the pull_seal/pull_close relationship, which would help an agent place it among 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?

Schema description coverage is 100%, and the schema already states 'The sealed record (its public half)' and 'The secret half (key, iv, nonce)'. The description largely restates this, adding only the loose `{"sealed": ...}` wrapper hint, so it sits at the baseline where the schema does the heavy lifting.

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

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

The description names a specific verb (opens) and resource (a sealed record) and even clarifies the two inputs (public half plus secret) and the two things returned (content and seal integrity). It is unmistakably a decrypt/verify operation. It stops short of naming the inverse sibling pull_seal, so there is no explicit sibling differentiation.

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: the agent learns this is the tool for a sealed record you hold the secret for, and the note that a non-opening seal is 'a finding, not a refused input' sets expectations for the call. However, no alternative (e.g. pull_seal, the inverse) is named and there is no explicit when-not 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 annotations it discloses cost ('costs 1 unit'), latency ('within 30 seconds'), determinism under seed, the engine/client split ('the engine plays no click and hears no input'), and partial-failure semantics (a refused drill name refuses the whole answer). These are real behaviours an agent could not infer from readOnlyHint/destructiveHint alone. It stops short of describing failure modes for the simulation path.

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

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

The content largely earns its place, but it is delivered as a single dense run-on block with nested parentheticals, so the essential 'what it grades' and 'how to call it' points are not front-loaded or scannable. Size is defensible for the complexity; structure is not.

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 restated, yet the description still explains the answer's shape (each drill's next level and score, trends over history). Combined with input-mode coverage, cost, latency and refusal rules, an agent has enough to call the tool 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 100%, so the baseline is 3, but the description adds genuine meaning: it explains that practice keys live in pull_schema, that practice.person configures the simulated player, and the format and effect of recorded rounds ('[{clicks_ms, taps_ms}] ... graded as played'). It goes beyond restating the schema.

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

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

It states a specific verb and resource ('Grades a practice of five drills') and enumerates the five drills, so an agent knows exactly what the tool computes. It does not, however, contrast itself against neighbouring pull_* tools such as pull_analyse or pull_replay, so sibling routing is left to the 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?

It spells out the input permutations clearly ('give a practice document ... or nothing, or seed alone, for the default practice of all five drills') and describes the iterative workflow where the returned session is fed back as the next practice's history. It gives context but no explicit when-not or alternative-tool guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond those: it explicitly states the operation costs no units and returns a hash.

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

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

A single, front-loaded sentence with an informative parenthetical. Every clause earns its place, and 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?

Output schema exists so return-value details are not required, yet the description still names the returned hash. With annotations covering safety and the input schema covering structure, the definition is 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 coverage is 100% and the schema defers key listing to pull_schema. The description adds meaning by enumerating what the prereg object contains (measures, conditions, trials, sessions, alpha, power, comparisons, correction), which helps an agent understand the parameter without a separate schema 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?

States a specific verb (reads) and resource (pre-registration) and clarifies the return value (its hash). It does not explicitly differentiate itself from sibling pull_* tools, 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?

Gives a clear usage context: record the returned hash in each session's prereg.hash before the run starts. No alternatives or when-not conditions are named, which keeps it from a 5.

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

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

With annotations only covering the safety flags (readOnly=false, idempotent=false), the description carries substantial extra context: it re-runs a twin (explaining the non-read-only, non-idempotent hints), reports which hashes failed, answers 200 with ok=false instead of erroring, and discloses a cost of 1 unit even on failure. Cost and failure-mode disclosure go well beyond what the schema and annotations provide.

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 dense sentences with no filler: the mechanical behavior comes first, then the outcome and cost semantics. The phrasing is slightly convoluted ('runs the twin again from what it records'), but nothing is padding and the key facts are 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?

An output schema exists, so return-value documentation is not required, yet the description still explains the ok/replays outcomes and the partial-match reporting. Combined with the cost notice and the twin re-run behavior, an agent has everything needed to call this correctly and interpret the result.

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

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

There is a single parameter ('session') whose schema description coverage is 100%, so the schema already documents it as the session document to recompute. The description adds no format, size, or sourcing detail beyond that. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a concrete verb and resource: recompute a session's recorded hashes and replay a twin session. An agent can tell this apart from most pull_* siblings (align, analyse, seal, close). It stops short of naming the sibling that creates the twin (pull_twin) or otherwise routing between them, so sibling differentiation is implicit rather than explicit.

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: it clarifies that a non-replaying session is a legitimate 'finding' rather than a rejected input, which shapes expectations. But there is no explicit when-to-use guidance, no prerequisites for having a session document or a twin, and no direction to alternatives among the many pull_* tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, but the description adds real operational context beyond them: it costs 1 unit, persists nothing ("Nothing is kept here"), returns both schedule and text, and grades randomness sources. These additions are consistent with the annotations, not contradictory.

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 and the trailing short sentences ("Returns the schedule and its text... Nothing is kept here. Costs 1 unit.") are crisp and high-value. The middle entropy sentence is long and slightly overloaded, and "research refuses software randomness" is stated twice, costing a little efficiency.

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 6-param, nested-spec tool with an output schema, the description covers everything an agent needs: what the spec controls, where its keys live, how entropy/grade/seed interact, persistence, cost, and the research restriction. Nothing material is left to guesswork.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: the mutual relationship between entropy (default os + hardware_seeded grade), seed (software grade), and entropy_hex + grade, plus the research interaction that rejects software randomness. This is genuine semantic value over the field-level docs.

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 ("Draws a schedule of perturbations") and enumerates the perturbation types, so the agent knows exactly what is produced. It also references siblings pull_schema (key list) and pull_seal (sealing), giving partial differentiation, though it never states how it differs from other pull_* generation 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?

Gives clear conditional guidance for choosing the entropy path (default OS randomness, seed, or entropy_hex with a grade) and an explicit exclusion (research refuses software randomness). It lacks any tool-level routing such as when to pick this over pull_lab, pull_practice, or pull_replay.

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 behavior, so the safety profile is covered. The description adds genuinely new context beyond them: the tool consumes no units/quota, and it previews the shape of the returned document tree, which is useful for an agent deciding whether to call 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?

Compact overall: one dense sentence defining scope followed by two short imperatives. The enumeration of session internals (onsets, states, intentions, follower's report, sealed schedule) is detailed but each item informs what the schema contains; the only mild weakness is that the actionable 'Call this first' directive sits at the end.

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 no further explanation, and with zero parameters and full annotation coverage the remaining burden is low. The description supplies the domain vocabulary an agent needs to interpret the schema, leaving little missing for a call-first introspection 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?

The tool takes zero parameters, so the baseline is 4 – there is nothing for the description to disambiguate beyond what an empty schema already conveys.

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

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

States a specific verb+resource (pull the schema of every document the pull engine reads) and enumerates the document types it covers, so an agent knows exactly what comes back. It does not explicitly differentiate itself from schema siblings in other domains (art_schema, video_schema), but the 'pull engine' scoping is clear.

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?

'Call this first' is an explicit sequencing directive that tells the agent when in the workflow to use it, and 'Costs no units' removes cost as a reason to hesitate. It stops short of naming alternatives or when-not-to-use conditions, so it is clear context rather than 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?

Annotations only cover safety flags; the description supplies the behavior that actually matters here: the service does not store, log or show the text or secret again, the key is fresh (implying non-idempotence), and the call costs 1 unit. This is exactly the kind of context annotations cannot convey.

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

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

Front-loaded with the core operation and dense with relevant detail; nearly every clause earns its place. The trailing entropy-grade sentences are packed and run-on, making them harder to parse than the rest.

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 7-parameter cryptographic tool with an output schema already present, the description covers purpose, lifecycle, cost, and secret-handling obligations. The seed-vs-entropy_hex-vs-grade interaction is the one area left slightly ambiguous.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: held_by defaults to L for the leader station, at_ns is the sealing time before start_ns, and the entropy/seed/entropy_hex/grade interaction determines the entropy grade that a research run accepts or refuses. It goes beyond the schema's per-field text.

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 ('Seals') plus resource ('a schedule's text') plus mechanism (SHA-256 commitment and ChaCha20 encryption under a fresh key) in the first sentence. It also situates the tool in the pull workflow by naming where content comes from (pull_schedule) and where results go (schedule.sealed, schedule.opened), letting an agent distinguish it from pull_open/pull_close/pull_schedule.

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?

Clear context: seal before the run, keep the secret, release cues at their moment, publish the secret into schedule.opened after the close. It also states a conditional constraint ('a research run refuses' software-graded seed). No explicit 'do not use this when...' or named alternative tool, so it stops short of a 5.

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

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

Annotations declare non-read-only, non-idempotent, non-destructive, and closed-world, but the description adds rich behavioral context: deterministic reproducibility (same seed/document gives same hash), cost model in units, queuing rules, session limits, schedule bounds, and free-plan refusal. This is well beyond what annotations provide.

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 dense paragraph of ~250 words, front-loaded with purpose but lacking structural breaks (e.g., bullets for cost/queueing). While much content is necessary, some sentences (e.g., parsing the cost formula) could be condensed, making it harder to scan quickly.

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?

Given the complexity, output schema presence, and 8 parameters, the description covers all critical aspects: input modes, defaults, cost, queuing, plan restrictions, and reproducibility. An agent has everything needed to decide when and how to call it.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful details beyond schema: default session count (20 or document's own), field semantics as a lattice between leader and follower, and clarifies planted gains range. It doesn't fully re-explain every parameter but compensates well for the high coverage.

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

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

States a specific verb (runs) and resource (twin sessions) plus the analysis output: significance count, rate with 95% interval, and pooled report hash. Distinguishes from siblings by naming ae_pull for hash compatibility and pull_schema for document keys.

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 describes when to use a twin document versus condition/coupling/planted versus field, and explains the default pair behavior. Also covers cost, queuing, and free-plan refusal (402), leaving no ambiguity about 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?

Annotations already declare the safe read-only, idempotent, non-destructive, closed-world profile, so the bar is lower. The description still adds real value beyond that: it flags the 'strict reader' behavior, notes the operation costs no units, and characterizes the verdict (valid fields vs. the offending key and reason).

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

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

Three tight sentences, front-loaded with the verb and resource, with no filler. Slightly dense but every clause carries information; 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?

An output schema exists, so return values need not be re-explained, and the description still summarizes the verdict shape. For a single-param validation tool it covers what is checked, the reference conventions, and the cost, leaving little an agent needs missing.

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

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

With 100% schema coverage the baseline is 3, but the description goes further by clarifying that forms and materials may be referenced either by shipped id or written inline, which is not stated in the schema. The nested shot object is also routed to raster_schema for every key.

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 ('Checks') and resource ('a shot document') and enumerates what is validated (name, size, subject count, length) plus the failure mode ('the key that is wrong and why'). This clearly separates it from raster_render (which renders) and raster_schema (which lists keys).

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 – validate a shot document via the strict reader, and it 'costs no units' – but the description never names alternatives like raster_render or raster_schema or states when-not to use it. An agent must infer the validate-before-render workflow.

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 write/openWorld/idempotent=false; the description adds substantial behavior beyond them — exact cost model (3 units + 1 per 1.6MP; 5 more for a still, 26.2 more for a crowd), asynchronous queued-job semantics (202 + job id, poll via GET /api/agents/jobs/<job>), and plan-gating with 402.

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, but the body is a dense, single-paragraph wall of text mixing cost, subjects, and job semantics. Every fact is relevant yet the packing hurts scannability; some pricing restatement 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?

An output schema exists, so return-format explanation is unnecessary, and the description still covers cost, async job polling, and plan gating. For a complex nested-subject tool it is nearly complete, though linking raster_schema for the shot document is only referenced from the schema rather than the description.

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% (baseline 3), but the description meaningfully enriches the otherwise opaque 'shot' object with concrete subject examples (zone vs terrain, world key, cut, crowd) and clarifies the width/height pairing rule and the effective 1920x1080 cap beyond the schema's per-field maxima.

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: 'Renders a shot ... as shot.png', and enumerates what the shot draws (forms, rig, country, sky/sun/shadow/haze). This clearly distinguishes it from siblings like raster_check, raster_schema, and the video_* render 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?

Gives strong context for use: it explains the world/zone subject forms, the default crowd, and the paid-plan requirement with 402 on the free plan. It stops short of naming alternatives (e.g. when to prefer raster_check first), so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive and not-open-world, so the safety profile is covered. The description adds one useful behavioral fact, 'Costs no units,' which is not in the structured data. Beyond that it does not describe caching, latency, or scope limits, so it is adequate but not rich.

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 claim ('Every key and range a shot document may use'), followed by an enumeration and two short supporting notes. It is dense but every sentence contributes; the enumeration is long but purposeful for a schema reference.

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 need not explain return values, and for a zero-parameter reference tool it adequately summarizes the content's scope and the world-key cross-reference. It is complete enough to use, though it could name related schema tools more explicitly.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is required, and nothing about parameters is left ambiguous.

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

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

States a concrete resource and scope: the set of keys and ranges a shot document may use, broken into camera, sun, air/fog, and subjects. This lets an agent recognize it as a schema/reference tool rather than an action tool. It does not explicitly contrast itself with sibling schema tools like video_schema or raster_check, so it falls short of full sibling differentiation.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The mention that the same keys go in a video clip's extra and the pointer to raster_render are cross-references, not routing instructions. An agent must infer that this is the reference to consult before authoring a shot.

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: cost of 1 unit, stereo WAV output, loop behavior (end crossfaded into start for repeat playback) versus the otherwise fading-out ambience, seed-driven variation of one-shots, and the explicitness that nothing is sampled from a recording. IdempotentHint=false is consistent with the seed discussion.

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 and mode selection are front-loaded, and every clause carries information despite the density. The long semicolon-chained sentences mixing mode selection, loop semantics and level semantics make it harder to scan than a bulleted breakdown would be.

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 format need not be described, and the description covers everything else an agent needs: mode choice, ranges and defaults, cost, determinism, and the no-sampling constraint. Nothing material is missing for an 11-parameter render tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: peak_db is framed functionally ('so a footstep and a thunder come back at one level'), raw as keeping the synth's own level, and a/b/c as per-sound parameters read from sound_list. The loop crossfade and default values are also clarified in prose.

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

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

States a specific verb and resource ('Renders one sound from the engine's own synth as a stereo WAV, or an ambience of the beds mixed together') and immediately names the two mutually exclusive modes. An agent can distinguish this from sound_list (catalog lookup) and voice_speak (speech synthesis) 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?

Explicitly routes between the two modes ('Give sound ... or give ambience: ...') and points to sound_list as the authority for the a/b/c meanings. It gives clear selection context but states no exclusions or prerequisites (e.g., what happens if both sound and ambience are supplied).

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, and an output schema covers the return payload, so the burden is low. Within that, 'Costs no units' is a genuinely additive cost/resource trait not present in the structured fields.

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

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

A single sentence front-loads the counts of sounds and beds, which is reasonable, but the long parenthetical inventory ('steps on twelve surfaces, doors and stairs, blows, thunder, splashes, a siren, animal calls, notes and the rest') is verbose and trails off with filler like 'and the rest'.

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

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

For a parameterless catalogue tool with an output schema describing return values and annotations covering the safety profile, the description is nearly sufficient. The main gap is the missing pointer to sound_effect for consumption and the unexplained a/b/c reference.

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

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

The tool takes zero parameters, so per the baseline no parameter explanation is required. The stray mention of 'what each of a, b and c does' refers to something outside this schema and adds confusion rather than clarity, but does not penalize an empty parameter set.

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 (twenty-one sounds plus seven beds) but is a fragment with no action verb, and the cryptic 'what each of a, b and c does' is never explained. It does not mention or contrast with the obvious sibling sound_effect, so an agent gets the inventory but not a crisp statement of what calling this tool does.

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

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

There is no when-to-use or when-not-to-use guidance and no reference to alternatives such as sound_effect for actually playing a sound. The only practical cue is 'Costs no units', which implies it is cheap to call but does not route the agent between tools.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is low. The description still adds real context beyond them: the call costs nothing, a pass never renews, pricing tiers ($1.00 one-time, then $20.00 with 1,500 units), and that purchasing requires a shared payment token over REST.

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?

Roughly 110 words for a zero-parameter read tool. It repeats the same fact twice ('that it never renews' and again 'A pass never renews') and devotes several sentences to pricing and purchase endpoints that this tool does not perform, padding a description whose actual job is one 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?

An output schema exists, so return-value explanation is not required, yet the description still glosses the field meanings. Five of the six fields plus pricing context are addressed; only the practical read workflow is left implicit.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds nothing parameter-related, and there is nothing to add.

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 resource (the account's plan) and enumerates what it returns: a pass with its unit window and end date, a card plan with period and renewal, owner state, amount paid, and pass_quote. It does not differentiate itself from any sibling tool, so it stays at 4 rather than 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?

It explicitly warns that buying is a REST call with a payment token and not this tool, naming POST /api/agents/subscribe and POST /api/agents/units as the alternatives. That is genuine when-not guidance, though it never states plainly when an agent should call this read tool instead of, say, usage or owner.

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

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

Annotations only cover the safety profile (readOnly/destructive/idempotent), and the description adds a great deal beyond them: the cost ('Costs 1 unit for any area'), the error contract ('an unknown or out-of-range knob is refused with the reason'), determinism of seed+chunk+knobs, and the exact modes in which files (PNG, heights.f32, terrain.obj, terrain.glb, features.json) are emitted. The non-determinism implied by idempotentHint=false is consistent with the per-call unit cost, so there is no annotation 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?

The core purpose is front-loaded in the first clause, which is good, but the remainder is one enormous semicolon-and-parenthesis run-on sentence that is hard to parse and forces re-reading. Almost every clause carries information, so length is defensible for an 11-parameter tool, but the lack of sentence breaks or grouping hurts scanability.

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 tool with 11 parameters, nested objects, and an output schema, the description covers what an agent still needs: the coordinate conventions (row 0 north, x east/y up/z south), the output modes and their file names, cost, error behavior, and the grey-scale math (height = greyFrom + grey * unitsPerGrey). Return-value detail is partly carried by the output schema, so nothing essential is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description materially enriches it: it supplies real working ranges that differ from the schema's generic ±65536 bounds (terrainAmp 0-40, terrainOctaves 1-5, ridgeHeight 0-400, step 1-16, area w/h 1-8) and explains ridgeX0/Z0/X1/Z1 as a hill along a line and range as the tiling scale. Many knobs (slopeLimit, clumping, palette, waterTable) are still only named, not explained, keeping it short of 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?

The opening clause gives a concrete verb and resource: 'Builds open country from a seed word and writes its ground as a greyscale PNG,' and it pins down the chunk/tile coordinate system. That is far more specific than a tautology, but it never names or contrasts a sibling such as world_heightmap or raster_render, so an agent still has to infer which generator is the right one.

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: the text explains that 'a landscape is one call' via area and that range 'fixes the grey scale... so separate calls tile,' which tells the agent how to combine calls. There is no explicit when-to-use-this-vs-alternatives guidance, no exclusions, and no prerequisite statements, so it stays at the implied-usage level.

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