wavetable-tools

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 still adds genuine value beyond them: it discloses that no account or project access is required and that output matches the /features surface, which helps the agent reason about auth and result parity. Return shape is left to the output schema.

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

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

Two tight sentences: capability inventory first, then the usage trigger and access constraint. Every clause carries information an agent needs; nothing is redundant with the name or the annotations.

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

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

For a read-only inventory tool with an output schema and full parameter coverage, the description supplies the remaining unknowns: what is included (pricing, limitations, docs links), the intended question type, and the no-auth requirement. 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?

Schema description coverage is 100% and the single optional 'category' enum is fully documented in the schema, so the baseline is 3. The description never mentions that results can be scoped by category or that omitting it returns everything, adding nothing beyond the schema.

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

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

States a specific verb ('Read') and resource ('Hyperwave's current app features') and enumerates the exact contents returned: workflows, pricing/availability, limitations, and documentation links. None of the sibling tools (session/render/export utilities) overlap, so an agent can select this immediately for product-inventory questions.

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?

'Use this for product capability questions and comparisons' gives a clear positive trigger, and 'No account or project access' rules out a class of mistaken invocations. No explicit when-not or named alternative is needed here because no sibling covers this territory, but the guidance is not fully exhaustive.

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. The description adds that it is 'pure calculation' and performs no rendering or data saving, which reinforces the safety profile with some context. It does not cover rate limits, authentication, 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?

Two tight sentences, front-loaded with the calculation outputs and followed by a scope clarification. No wasted words.

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

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

The output schema exists, so return values need not be explained. Annotations cover safety, the schema covers parameters, and the description states the calculation scope and non-rendering nature. Complete for an idempotent pure calculation tool.

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

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

Schema description coverage is 100%, so all three parameters are fully documented in the schema. The description adds no parameter semantics beyond what the schema provides. 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?

States a specific verb ('Calculate') and resource ('packed float32 mono WAV sample count, payload bytes, total bytes, and durations'). It distinguishes itself from audio rendering and saved data, but does not name or differentiate from its sibling tools (describe_wav_encoding, list_export_targets).

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

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

The phrase 'Pure calculation; no audio rendering or saved data' implies when this tool is appropriate and excludes rendering/saving tasks. However, it does not name alternatives or give explicit conditions for choosing it over siblings. Usage is only implied.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description usefully adds that checkpoints persist in shared version history and the exported preset. However, it never says whether action=delete irreversibly drops a checkpoint or what happens to untracked edits, which is the key risk for a destructive-annotated tool.

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

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

Three short sentences, front-loaded with the primary action before the secondary management modes. Zero filler, though the phrase 'with a short description' is slightly loose relative to the 'label' param.

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-parameter mutation tool with no output schema and 0% schema description coverage, the description covers the semantics of the create/rename/delete flow but leaves the required sessionId, token, and baseRevision unexplained. An agent could call it, but might supply an arbitrary baseRevision without understanding its role.

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

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

Schema coverage is 0%, so the description must carry parameter meaning; it explains label (short description), the action enum values, and checkpointId for managing existing versions. It says nothing about sessionId, token, or especially the required baseRevision (likely concurrency control), leaving three of six parameters undocumented.

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

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

Specific verb and resource: 'Create a restorable version of the current shared preset' with a clear scope (shared preset, version history). It also discloses the secondary modes (rename/delete via action), so the agent understands the tool is not purely a create. It does not explicitly name restore_session as the counterpart, which keeps 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?

'Also use before a substantial experiment' gives an explicit trigger condition, and the closing sentence tells the agent to route rename/delete management through action + checkpointId rather than another tool. No when-not guidance or named alternative for the restore side, but the usage context is clear.

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 mark this as destructive, but the description adds valuable context beyond them: the deletion is permanent, presets should be saved/exported first, and some presets survive the deletion. It does not cover authentication requirements or revision-conflict behavior, but it meaningfully clarifies the destructive consequence.

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 concise sentences with the destructive action front-loaded and the important pre-save guidance immediately following. Every sentence earns its place.

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

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

For a destructive operation, the description adequately warns about permanence and preservation of some presets. However, it does not explain authentication via token, concurrency via baseRevision, or what the caller should expect after deletion, leaving material gaps for correct invocation.

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

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

Schema description coverage is 0% for all three required parameters (sessionId, token, baseRevision). The description provides no information about their roles, formats, or semantics, so it fails to compensate for the undocumented schema.

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

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

The description states a specific verb and resource: permanently delete the temporary collaborative workspace. This clearly distinguishes it from sibling tools like checkpoint_session, restore_session, and edit_session, which preserve or modify rather than permanently remove the session.

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

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

It gives a clear prerequisite: save or export a preset first. It also notes that downloaded and normally saved presets remain available after closure. However, it does not explicitly compare this tool with alternatives such as checkpoint_session or explain when to avoid closing a session.

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

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

Annotations already declare it is a non-read-only, non-destructive, non-idempotent, closed-world mutation, and the description adds real context on top: fixed 24-hour lifetime, exact return payload, secret-handling instruction, and the guarantee that only project state (never prompts or analytics) is stored. No rate limits or capacity limits are mentioned, which is the remaining gap.

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

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

Front-loaded with purpose and lifetime, then the return values, then handling instructions. Most sentences earn their place, though the trailing 'Begin with read_session and edit_session; no account is needed' bundles two unrelated points awkwardly.

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

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

With no output schema, the description usefully enumerates return values (sessionId, token, editorUrl, revision, state) and states the expiry, so an agent knows what it gets back. The undocumented 'name' input is the one incompleteness.

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

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

Schema description coverage is 0% and the single 'name' parameter is never mentioned in the description, despite the odd default 'Agent preset' that an agent would benefit from having explained. The description does compensate by documenting return fields, but not the input.

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

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

States a specific verb and resource (create a private temporary collaborative workspace) with a concrete distinguishing trait, the 24-hour expiry. It also names read_session and edit_session as the follow-on tools, so an agent can place it among the siblings without opening any schema.

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

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

Gives clear operating context: no account needed, share editorUrl with the user, keep the token private, and continue with read_session/edit_session. It stops short of stating when NOT to use this (e.g., when a session already exists and checkpoint_session or restore_session applies).

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so safety needs no restating; the description instead adds the meaningful behavioral facts: two output granularities (compact inventory vs per-kind detail) and that returned templates and ids are stable and reusable in edit_session. It does not discuss result size or shape, which matters given 120+ enum values, so it is good but not exhaustive.

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

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

Three short sentences, front-loaded with the resource and capabilities before the parameter behavior and the downstream usage tip. No filler and nothing redundant with the schema.

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

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

There is no output schema, so the description must cover return content, and it does list the salient parts (types, inputs, numeric controls, graph sources, full default templates) plus the compact-vs-detail distinction. It stops short of describing the per-kind detail structure an agent would use to build edit_session changes, which is the main remaining 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?

With only one parameter and 0% schema description coverage, the description carries the semantics: it declares the parameter optional and explains the behavioral difference between supplying and omitting it. It does not explain that the enum values correspond to node kind identifiers or what a given kind's detail payload contains, leaving the enum to self-document.

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 opens with a specific verb ("Discover") and a concrete resource (Hyperwave node types, inputs, numeric controls, graph sources, default node templates), which is clearly distinct from the other describe_* sibling (describe_wav_encoding) and from session/render tools. An agent can tell exactly what this returns without opening the schema.

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

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

It spells out both invocation modes explicitly ("Pass a kind to retrieve details; omit it for the compact inventory") and directs the agent to the downstream consumer ("Use these templates and stable ids in edit_session changes"). No exclusion against an alternative tool is stated, but no competing tool exists for this lookup, so context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds the nuance that these are 'actual' encoder values (not theoretical defaults) and lists the returned fields, but the field list largely duplicates the existing output schema.

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

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

One sentence, zero filler, with the verb and resource front-loaded and the format constraint and returned fields trailing in order of importance. Nothing needs trimming.

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 read-only tool with a published output schema and full safety annotations, the description covers what is being read and for which formats. The only gap is the absence of routing guidance against the two sibling 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?

The single parameter has 0% schema description coverage, but its enum already constrains it to float32/pcm16. The description restates those two accepted values, which compensates for the missing prose, yet adds no new meaning (no format defaults, output differences, or validation notes).

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 ('Read') plus a precise resource ('Hyperwave's actual WAV encoder layout') scoped to two formats, so the agent knows exactly what comes back. It does not distinguish itself from siblings like calculate_frame_size or list_export_targets, which caps it below 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: 'actual ... encoder layout' suggests inspecting real encoder output rather than computing it, which quietly separates it from calculate_frame_size. There is no explicit when-to-use, when-not-to-use, or named alternative, so it stays at minimum viable.

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: declares atomicity, undoability, merge semantics for concurrent edits, the SESSION_CONFLICT failure mode, automatic checkpointing of previous state for significant agent batches, and post-conflict recovery advice. This is exactly the mutation/conflict context the destructiveHint annotation 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?

Every sentence carries a distinct operational fact and the core action is front-loaded in the first clause. Dense, but nothing is redundant and the example path makes the abstract path format concrete.

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

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

For a destructive, non-idempotent mutation tool with annotations but no output schema, the description covers conflict handling, revision pinning, path format, and checkpointing. It stops short of describing auth requirements (token), what success returns, or other error codes, leaving a small gap an agent may need.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'changes' paths well with a concrete array example and explains baseRevision's provenance, plus hints at checkpoint via 'automatically checkpoint the previous state', but token, sessionId, actor, label, and the value/remove fields of each change are entirely unexplained.

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

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

States a specific verb ('Apply') and resource ('one atomic, undoable batch of changes to the shared preset'), making it clearly distinguishable from read-only siblings. The only slight wobble is calling the target a 'shared preset' while all parameters reference a sessionId/session, which could momentarily confuse an agent.

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

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

Gives concrete routing instructions: take baseRevision from read_session, use describe_nodes templates when adding nodes, and never blindly replace the whole document after a conflict. It lacks explicit when-not-to-use guidance (e.g. restore_session for rollback or checkpoint_session for manual snapshots), which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is well covered by structured data. The description adds real value by disclosing that results include steps, caveats, and primary sources, but it says nothing about pagination behavior despite limit/cursor parameters existing. 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?

Two tight sentences with the content scope first and the filtering mechanism second; nothing is wasted. Slightly penalized only because the front-loaded scope contains the import/export ambiguity.

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 unnecessary and correctly omitted. However, for a 4-parameter paginated list tool, the description never accounts for limit/cursor and carries the naming inconsistency, so it is not fully complete.

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

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

Schema description coverage is 0%, so all four parameters rest on the description. It mentions 'exact slug' (usefully signaling exact-match semantics) and 'category', covering only two of the four parameters. The pagination pair, limit and cursor, is completely undocumented in both the schema and the description, leaving a real gap.

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

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

The description states a read verb and enumerates the resource contents (formats, steps, caveats, sources), but it calls these 'synthesizer import formats' while the tool name is 'list_export_targets'. That import/export mismatch creates ambiguity about what is actually being listed. The resource is broadly identifiable, but the internal inconsistency keeps it from being a clean 4-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?

The description implies usage through 'Filter by exact slug or category', telling the agent how to narrow results. However, it names no alternative tool and gives no explicit when-to-use or when-not-to-use condition relative to the sibling tools. Usage is inferable but not directed.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds meaningful workflow context (read-after-conflict, read-before-editing-old-revision) and clarifies that checkpoints are restorable states. However, it never mentions the required 64-hex token as an auth requirement or what happens on an invalid/expired session.

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

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

Three short sentences, zero filler, with the returned-field list and the checkpoint flag guidance front-loaded. Every sentence carries actionable information.

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

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

With no output schema, the description compensates by naming the fields returned (preset, revision, expiry, checkpoint summaries). The remaining gap is auth semantics for the required token parameter and error/expiry behavior on the session itself.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains the checkpoints flag well ('retrieve restorable states'), but token and sessionId are left to their names/patterns with no guidance on where the token comes from or what an invalid one does.

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 ('Read the shared preset, current revision, expiry, and checkpoint summaries') and enumerates what is returned. It is clearly distinguishable from edit_session, checkpoint_session, and restore_session by name, though it never explicitly names a sibling as an alternative.

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

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

Gives concrete conditional guidance: 'Include checkpoints=true to retrieve restorable states' and 'Always read after a conflict and before editing an old revision.' This is real when-to-use advice, but it offers no exclusions or pointers to wait_for_changes / describe_nodes for other state-inspection needs.

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 safe, idempotent, read-only behavior, so the description's main added value is the bounded-rendering caveat and the promise that unsupported nodes are reported instead of silently passed through — important for trusting the output. It still leaves 'bounded' undefined and says nothing about token scope or failure modes, so it is not fully transparent.

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 tight sentences, front-loaded with the action and mechanism, then outputs, then the bounded-rendering caveat, then the alternative. Every sentence carries unique information with no redundancy.

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

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

With no output schema, the description does well to enumerate the three return artifacts (preview WAV, wavetable WAV, preset archive), which an agent needs. However, for a tool whose entire parameter set is undocumented in the schema, omitting any parameter guidance leaves a real hole for correct invocation.

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

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

Schema description coverage is 0% for all three required parameters (sessionId, token, revision), and the description never explains what any of them are — no mention of token provenance, revision semantics, or how sessionId identifies the session. 'Exact shared revision' faintly gestures at the revision param, but this is far short of compensating for the schema gap.

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

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

States a specific verb and resource ('Render an exact shared revision') plus the execution mechanism ('Hyperwave's shipped WASM engine without an open browser'), which cleanly separates it from sibling tools like edit_session, read_session, and checkpoint_session. An agent can tell what it produces 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?

Provides a clear usage context ('without an open browser') and an explicit off-ramp for the heavier case ('Open editorUrl for larger interactive renders'). It does not name any sibling tool as an alternative, so the when-to-use guidance is contextual rather than fully comparative.

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 meaningful behavior beyond annotations: it auto-snapshots the current preset as a checkpoint first (safety/reversibility), enforces optimistic concurrency via exact revision, and that both participants see the restored state (shared/collaborative). These details exceed the destructiveHint=true and non-idempotent flags provided.

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

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

Three short sentences, front-loaded with the core action, then preconditions, then collaborative effect. Every sentence carries distinct information with no 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?

For a destructive, non-idempotent mutation with no output schema and 0% schema coverage, the description covers concurrency and safety well but leaves token/sessionId semantics and any response shape unaddressed. Adequate but with clear parameter gaps.

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

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

Schema coverage is 0%, so the description must carry param meaning. It clarifies baseRevision ('exact current revision') and checkpointId (the checkpoint to restore), but says nothing about token (auth credential) or sessionId, leaving two of four required parameters unexplained.

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

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

States a specific verb+resource: 'Restore a checkpoint as a new shared edit.' An agent can tell this is a checkpoint-restore operation. It doesn't explicitly name siblings like checkpoint_session or edit_session, so no explicit differentiation, but the purpose is unambiguous.

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

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

Provides a clear precondition: 'Requires the exact current revision,' which tells the agent when this call will succeed. However, it does not state when to prefer restore over edit_session or when-not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds genuinely new behavior — it blocks up to ~20s and returns changed=false on timeout instead of erroring. It leaves out whether repeated polling is expected or any rate/retry guidance, so it is good but not complete.

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

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

Three short sentences with zero filler: the action and time bound come first, the return contract second, the workflow guidance last. Nothing is repeated from the schema or annotations.

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

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

There is no output schema, so the description carries the return-value burden; it does state the timeout result and "the current state" but does not say what that state contains or how afterRevision should be sourced. Combined with 0% parameter coverage, an agent still has gaps before calling correctly.

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

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

Schema description coverage is 0% across four parameters. The description only indirectly gestures at afterRevision ("newer revision") and timeoutMs ("up to 20 seconds"); token and sessionId are never explained, and the 20s figure conflicts in spirit with the 15s default without clarifying that timeoutMs is configurable.

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: wait for a newer shared revision, with the blocking window quantified. It implicitly separates itself from read_session and edit_session by describing a wait-until-changed behavior, but never names those siblings explicitly.

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

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

"Use while collaborating with the user, then inspect their changes before the next edit" gives a concrete usage context and a follow-up action. It does not name an alternative (e.g., read_session for immediate state) or say 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.