Onepin

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds real substance on top: irreversibility ('cannot be resumed'), cost consequences ('credits already spent are not refunded'), partial-output loss ('finished lines are not delivered'), and the no-op behavior for already-finished runs. This is exactly the context an agent needs before a destructive call.

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 short sentences, front-loaded with the action and its permanence, then consequences, then the confirm gate. 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?

With an output schema present, return-value detail is unnecessary, and the description covers the remaining agent-relevant facts: irreversibility, billing/partial-output effects, confirmation semantics, and the already-finished edge case. Nothing material is missing 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%, so the baseline is 3, but the description goes beyond the schema by framing confirm=false as a preview to 'show the user' and clarifying that confirm=true is what makes the stop permanent. It reinforces rather than merely repeats the parameter docs, though it adds no new format or constraint detail.

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 and resource ('Stop a run') plus a scope qualifier ('still in flight'), which cleanly separates it from read-oriented siblings like get_run_status, list_runs, and download_run. An agent can identify the operation 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 states the operative condition ('a run that is still in flight') and explains the confirm=false dry-run path versus the confirm=true path, which is genuine when-to-use guidance. It stops short of naming an alternative tool (e.g., get_run_status) for agents that only want to inspect state.

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 idempotent=true, so the safety baseline is set; the description adds genuinely non-obvious behavior — the server finds branches and rewires every retry edge itself, and the first call without confirm is a dry-run that yields an edit_token. It stops short of restating that replace=true removes existing checks and their retries, leaving that blast radius to the 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?

Four short sentences, zero filler, purpose front-loaded before mechanism and routing. Every sentence contributes something an agent would not get from the structured fields alone.

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

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

With an output schema present and full annotation coverage, the description needn't explain return values, and it handles the hardest part — the two-phase token protocol and server-side edge rewiring. A small gap remains for a destructive tool: it never warns in its own words that replace=true deletes unlisted checks, nor notes the ten-minute edit_token expiry.

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 each of the eight parameters is already documented in-field (target, confirm, replace, edit_token, checks all have descriptions). The description adds only the sequencing semantics of confirm plus edit_token, restating the target scoping that the schema already explains. Baseline 3 is correct when the schema carries the load.

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 ("Change the quality policy on voice generators") and scopes it to a saved workflow. The second sentence clarifies that this is a graph-level rewrite, not a hand-wired edit, and the third sentence names patch_workflow as the sibling for the narrower single-node case, so an agent can separate the two without reading 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?

Explicitly routes the agent: use target to scope by ids or locales, use patch_workflow instead when changing a threshold on one node. It also gives the mandatory confirm-then-edit_token sequence. What's missing is the when-not condition around replace=true clearing unlisted types, which only appears inside the schema field text.

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 (non-destructive write, closed world, non-idempotent). The description adds useful behavior beyond that: the server draws the graph, source_audio is wired to an Export with no voice/generator, checks drop failed clips unless their fail is wired to an Export, and confirm=false creates nothing. It does not discuss permissions or limits, but is strong for an 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?

Every sentence carries operational information, and the core instruction is front-loaded. Some phrasing is terse to the point of ambiguity ('Name checks to score it'), but there is no 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?

Given the existing output schema and rich parameter descriptions, the description covers the critical workflow: use uploaded clips, source_audio is wired to Export, checks drop failed clips unless fail is wired to Export, and confirm=true commits. Minor gaps remain around omitted checks behavior and explicit prerequisites, but nothing essential for correct invocation 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 the baseline is 3. The description still adds practical meaning: it tells the agent to supply uploaded clips with languages, how checks should be named, and that a check's fail routing matters ('a check drops its failed clips unless you wire its fail to an Export'), which goes beyond the raw on_fail 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 and resource: build a workflow around audio the user already has. The phrases 'source_audio is wired to an Export, no voice or generator' distinguish it from script-based workflow creation siblings. An agent can tell this is the bring-your-own-audio path without opening another 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 prerequisites ('Give the uploaded clips with their languages') and an explicit two-step pattern ('Call again with confirm=true'). It does not name an alternative sibling such as create_workflow_from_intent or explicitly say when not to use this tool, so it falls 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 a non-read-only, non-idempotent, non-destructive, non-open-world mutation, so the safety profile is covered. The description adds real behavior on top: the two-phase validate-then-create gate, that no writes occur without confirm=true, and that the call may instead return a pre-existing matching workflow. It does not cover name collisions or error handling.

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 dense sentences, front-loaded with the action and its precondition, no filler. Slight cost: the first sentence is grammatically malformed ('a definition validate_workflow_definition approved') and the second conflates two distinct outcomes ('what to show the user, or a workflow you already have'), requiring a re-read.

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

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

The token requirement, dry-run semantics, force override, and the returned workflow_id are all stated, which is sufficient given an output schema exists and annotations cover the mutation profile. Nothing an agent needs before calling is absent.

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 carries the parameter burden and the baseline would be 3. The description still adds meaning the schema does not: that validation_token is bound to these exact definition bytes, tying the token to the payload rather than treating it as an opaque string.

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 (create a workflow) and pins down the exact provenance of the input: a definition previously approved by validate_workflow_definition. That provenance requirement is what separates it from siblings like create_workflow_from_intent and create_workflow_from_template, which need no validation_token.

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

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

Explicit preconditions and alternatives: it requires the token from validate_workflow_definition for these exact definition bytes, explains confirm=false as a no-op preview, and force=true as the escape hatch when the user has already chosen to build new rather than reuse an existing workflow. The when/when-not is fully specified.

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 the most important behavioral trait: the server derives nodes, ports, translator and quality checks, so the caller should not pre-specify them, and confirm=false is a pure preview that creates nothing. That is real value over the structured hints. It stops short of warning that the tool is not idempotent — repeating confirm=true presumably builds a duplicate — and says nothing about failure modes or permissions.

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 and a fragment, front-loaded with the action and the routing decision, with the confirm cycle last. Every sentence carries a distinct decision the agent must make; nothing is restated 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?

For a 12-parameter, output-schema-backed creation tool, the description covers intent, the dry-run gate, and the alternative tool, which is what an agent needs to call it correctly. It leaves the roles of force, pronunciation_remediation, audio_format and script_has_markup entirely to the schema descriptions, which is acceptable but means the description alone is not a full briefing.

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 already high, but the description adds the conceptual constraint the schema cannot express: pass the languages with their voices and ONE script route, letting the server fill the rest. That reframes 12 parameters into a simple intent payload and tells the agent which of the many optional fields it should deliberately leave out.

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

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

The description gives a specific verb and resource ("Build the ordinary workflow") plus the decisive scope: it is driven by the languages the caller names and the server assembles the graph. It explicitly contrasts with the sibling create_workflow ("Prefer this over create_workflow ... Author a definition only for a shape this refuses"), so an agent can route between the two without reading 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?

It states the when (you have languages + voices + one script route), the when-not (only author a definition for shapes this refuses), the named alternative (create_workflow), and even the calling sequence (first call shows what would be created, then call again with confirm=true). Nothing about tool selection is left to inference.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, but the description adds the crucial non-obvious behavior: without confirm=true nothing is cloned and you get back the pipeline/voices/quality gates as a preview, while force=true skips the reuse check. This is exactly the extra 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?

Purpose is front-loaded, followed by the usage precondition and then the confirm/force behavior. Dense but every sentence earns its place; the parenthetical 'asking for audio is not picking one' is slightly indirect but useful.

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, 100% schema coverage, and full annotations, the description covers the one thing an agent could get wrong — that the default call clones nothing and returns a preview. 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%, so the baseline is 3. The description still adds the intent behind confirm ('to show them') and force ('skips the reuse check') beyond the schema's terse wording, earning a modest lift.

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+resource+scope: 'Clone a template into this workspace as a runnable workflow.' That is clearly distinct from create_workflow / create_workflow_from_intent by virtue of the template source, though no sibling is named 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?

'Call only after the user picked THIS template — asking for audio is not picking one' supplies a real precondition and an anti-pattern (asking for audio isn't selection). It stops short of naming the alternative tools (create_workflow_from_intent) an agent should use instead.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the deletion is permanent ('cannot be restored') and the only remedy is re-saving. It does not mention permissions or error behavior, but the irreversibility disclosure is the key missing piece.

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 operation and its scope, followed immediately by the consequence. Every sentence earns its place 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?

With one required parameter, full schema coverage, an output schema, and annotations covering safety semantics, the description supplies the remaining critical fact — permanence of deletion. Only fine-grained details like failure modes or permissions are absent, which is acceptable at this complexity.

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 itself explains that entry_id comes from list_dictionary_entries. The description adds nothing about the parameter, so the baseline 3 applies when structured data carries the full burden.

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 ('Remove one entry from the workspace pronunciation dictionary'), which is clearly distinguishable from the sibling list_dictionary_entries and save_dictionary_entry. It stops short of naming those siblings, but an agent can identify the operation immediately.

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 phrase 'only saved again' weakly hints that save_dictionary_entry is the recovery path, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer the context but is given no 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 cover safety (idempotentHint=true, destructiveHint=false), so the bar is lower; the description still adds real behavior: the completed-run gate and the refusal for unfinished/failed/cancelled runs. It also discloses the link-expiry trait ("the link stops working at expires_at, so fetch it now"), which is a time-sensitive behavior not expressible in annotations. The specific return fields are already carried by the output schema, so that portion is redundant.

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: capability, routing/precondition, then return-and-expiry warning. The most decision-relevant information (bulk ZIP, completed-only) 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 documentation is not required, and annotations cover the safety profile. Combined with the explicit precondition and expiry warning, an agent has everything needed to select and call this 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 description coverage is 100% and both required parameters (workflow_id, run_id) are documented in-schema with sourcing hints ("from run_workflow or list_runs", "from list_workflows. Never invent one"). The description adds no additional parameter meaning beyond the schema, 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 and resource — fetching a single ZIP link containing every audio file from a run — and implicitly contrasts with the sibling get_run_outputs by positioning it as a bulk alternative to per-line downloads. An agent can distinguish it from get_run_outputs, get_run_status and list_runs without opening any schema.

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

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

Gives an explicit preference rule ("Use this instead of downloading lines one at a time") and an explicit precondition with its failure mode ("Only completed runs can be exported; an unfinished, failed or cancelled run is refused"). Both the when-to-use and when-not-to-use cases are covered.

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 and openWorldHint=false, and the description reinforces this with the memorable 'Creates nothing, charges nothing, asks nothing'. It also discloses a non-obvious behavioral trait: the workflow identity is not inferred, so the agent must confirm with the user. It lists the key return fields even though an output schema exists, which is mildly redundant but useful for at-a-glance decision making.

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 short sentences, front-loaded with the core action and the safety guarantee; every sentence carries information. The closing clause ('Nobody was asked which workflow this is...') is somewhat cryptic in phrasing, slightly reducing polish.

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 needn't enumerate returns, and it still summarizes the decision-relevant ones (credits, can_run, alternatives). Combined with annotations covering the safety profile, an agent has enough to call it correctly; only the explicit run_workflow follow-on linkage 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?

Schema coverage is 100%, so workflow_id, script_text and source_language are already fully documented in the schema, including the critical 'same text for estimate_run and run_workflow' constraint. The description adds no parameter-level detail of its own, 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 - 'Price a run before starting it' - which unambiguously distinguishes it from the mutating sibling run_workflow. An agent knows immediately this is a dry-run cost estimator, not an execution tool.

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?

'Price a run before starting it' plus 'confirm it and the price with the user before anything spends' clearly establishes the pre-execution context and the required user-confirmation step. It stops short of explicitly naming run_workflow as the follow-on action, leaving that inference to the agent (though the schema hints at the pairing).

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 readOnly/openWorld; the description adds the substantive behavior: a hard cap of three results, results are "vetted but not ranked," and no audio is returned. It also discloses the intended human-in-the-loop contract, which is exactly the kind of trait 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?

Four short sentences with the exclusivity claim and the call-order rule front-loaded. No filler, no restatement of the title, and the closing imperative lands last where it is most actionable.

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 an 11-parameter, all-optional search tool with an output schema and full schema coverage, the description supplies everything the schema cannot: result count, ranking posture, absent audio, and the preview handoff. Return-value details are correctly left to 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 description coverage is 100% and each parameter's own description already carries the hard-filter-vs-style distinction and the cursor rule, so the description adds little parameter-level meaning. Its only implicit parameter reference ("a valid catalog_voice_id") does not map cleanly onto any schema field, which is mildly confusing but not harmful. 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 ("Search for voice candidates") and immediately stakes exclusivity: "the ONLY tool that may search or recommend voices." An agent can separate this from list_providers, preview_voice and set_workflow_voice without reading any schema.

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

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

Gives an explicit ordering rule ("Call before preview_voice unless the user named a valid catalog_voice_id") and an explicit constraint ("Never pick a voice for the user"), plus the downstream step (preview_voice each to compare). When-to-use, when-to-skip, and the alternative are all named.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds non-obvious context beyond that: it returns the clip's size and 'never the audio,' and clarifies the downstream wiring. No permissions or failure modes are mentioned, but with annotations carrying the safety burden this is solid.

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 core action and precondition, followed by the return clarification and downstream usage. Zero filler; 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?

Output schema exists so return values needn't be spelled out, and annotations cover the safety profile. The description completes the picture with the upload sequence and the consumer of upload_id, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented (upload_id's origin and workflow_id's optional attachment). The description adds meaning beyond the schema by explaining what upload_id is ultimately for (source_audio node line, language, script), which the schema does not.

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

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

States a specific verb ('Register') and resource ('an audio clip') with the precondition that distinguishes it from its sibling: 'whose bytes you already PUT to an upload_url.' An agent can tell this is the second step after upload_audio_file 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?

Clearly places the tool in the upload sequence (bytes already PUT) and tells the agent what to do with the result: pass upload_id to a source_audio node line with language and script. It stops short of explicitly naming upload_audio_file as the prerequisite, so the sequencing is inferred rather than stated.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, closed-world. The description adds genuinely new behavioral context: the call returns character/line counts and detected language but 'never its text', which tells the agent what it can and cannot rely on afterwards. That is real value beyond the annotation set, though it says nothing about failure modes or what happens if the PUT never occurred.

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

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

Two sentences, both front-loaded with the action and then the payoff. No restatement of the name or 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?

An output schema exists, so return values need not be spelled out, yet the description still usefully characterizes them and explains the handoff to a source_script node. The only meaningful omission is that the upstream prerequisite (upload_script_file / the PUT step) is implied rather than named.

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 (upload_id, workflow_id) are already fully documented in the schema, including the workflow_id omit-to-keep-in-workspace semantics. The description only reinforces upload_id's provenance, 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 ('Register a file whose bytes you already PUT to an upload_url') and implicitly scopes itself against the sibling upload_script_file by making clear this is the completion half of a two-phase upload. An agent can distinguish it from upload_script_file 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?

Gives clear sequencing context (bytes already PUT to an upload_url) and prescribes the downstream usage: 'Pass the upload_id to a source_script node as input_type="file", upload_ids=[upload_id]'. It stops short of explicitly naming upload_script_file as the required predecessor, leaving that inference to the schema's upload_id description.

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 and openWorldHint=false, so safety is covered. The description adds real context beyond that: the balance is 'spendable', usage is measured 'against quota' for 'this billing period', and credits have a reset date — scoping the data the agent will receive.

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 purpose, then the distinguishing detail. Slightly redundant — 'this billing period's usage against quota' re-treads the opening line — but each sentence carries routing or scoping value.

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 needn't document return structure, yet it still signals the shape of the response (balance, quota usage, reset date). Zero-param, read-only, no auth caveats left unstated — 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Nothing in the text conflicts with 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?

States a specific resource (credit balance) and its three components — remaining credits, period usage, reset date — with a concrete verb. It also explicitly carves itself apart from estimate_run by naming the cost-estimation sibling it is 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?

Explicitly frames the question it answers ('how many credits are left' without pricing a run) and names the alternative (estimate_run) plus the condition that selects it (what a run will cost / whether balance covers it). No inference required.

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 and openWorldHint=false, so the safety profile is covered. The description adds the prerequisite that voice_map entries need real voices from find_voices, which is genuinely useful context, but it otherwise restates return contents that the output schema already carries.

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 with no filler, and the no-argument versus with-argument split is front-loaded. The leading sentence is a verbless fragment, which slightly hurts readability but not economy.

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 explained, and the description covers both invocation modes plus the find_voices prerequisite. Nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 100% and the single node_type parameter is already documented in the schema. The description's note that omitting it lists every type adds marginal semantic value over the schema's 'Omit to list every type first', so the 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?

The description names the resource precisely (node types, a node's config_schema, inputs and outputs) and distinguishes its two modes by argument presence. It is specific enough to separate from siblings like list_providers or validate_workflow_definition, though the opening fragment 'The node types you can use' lacks a clear verb and reads elliptically.

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 explicit when-to-use guidance for each mode: omit the argument to enumerate types first, pass node_type to get the schema. It also states a prerequisite ('read it before writing its config') and routes to the sibling find_voices when a generator's voice_map is involved.

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 readOnlyHint already set, the description still adds substantial context beyond annotations: no playback side effect occurs here, the URLs are short-lived and must not be cached, and the per-entry output shape is disclosed. These are operationally important traits not captured by 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?

Every sentence earns its place: purpose, precondition, safety guard, output shape, and caching warning. The critical precondition is front-loaded right after the purpose.

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

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

For a read tool with full schema coverage and an output schema, the description covers the falling-behaviors an agent needs: sequencing, no-playback constraint, URL ephemerality, and entry structure. Nothing required for correct invocation 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% and both parameters are documented in the schema (including provenance hints like 'from list_workflows'). The description adds no per-parameter meaning beyond what the schema already provides, 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 ('List the audio a run produced') with scope detail ('one entry per output node'). It clearly distinguishes itself from siblings like get_run_status (status vs. outputs) and download_run (listing vs. downloading).

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

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

Gives an explicit precondition tied to a named sibling ('Call once get_run_status reports completed') and adds a workflow guard rail ('ask the user before you play anything'). This tells the agent both when to call and what not to assume.

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 (readOnlyHint=true, openWorldHint=false), and the description adds genuinely behavioral context beyond them: this is a polling tool, its terminal states, and the concurrency rule against overlapping runs. It doesn't discuss polling cadence or rate limits, 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?

Three short sentences, zero filler: purpose first, then the operational rule, then the return payload. Every sentence earns its place and the most actionable content (polling and the no-second-run rule) 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, yet the description still enumerates the key returned fields as a convenience, and it fully specifies the polling lifecycle and concurrency constraint. Nothing an agent needs to invoke this 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 required parameters (run_id, workflow_id) are already documented in the schema, including provenance and the 'never invent one' warning. The description adds no parameter-level meaning beyond that, 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 states a specific verb ('Check') and resource ('how far a run has got'), and the returned field list (status, finished_steps, total_steps) makes the progress-monitoring purpose concrete. It is clear but doesn't explicitly contrast itself with the nearest sibling, get_run_outputs, 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?

It names the exact trigger ('Poll this after run_workflow'), the terminal conditions that end polling (completed, failed, cancelled), and an explicit prohibition ('do not start a second run while one is in flight'). That is when-to-use, when-to-stop, and a negative constraint in two sentences.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the markdown mode is written for direct display to the user (pipeline, nodes, voices, gates), while include_definition exposes the editable graph that update_workflow consumes.

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 sequencing, then flag semantics. No filler, no repetition of the schema's type 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 an output schema present and read-only annotations in place, the description only needs to cover selection and mode intent, which it does. The three response modes (markdown page, structured fields, editable graph) are all accounted for.

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, and the description clears that bar by explaining the intent behind each flag rather than restating types: markdown=true for user-facing display vs false for fields only, and include_definition=true specifically to feed update_workflow.

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 ('Fetch one workflow') and characterizes the payload precisely ('as a markdown page describing what its graph does'), which separates it from list_workflows and get_node_info. An agent knows exactly what it gets back before 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?

Gives an explicit sequencing rule ('Call after list_workflows') and conditions for the two optional flags, including the update_workflow round-trip. It stops short of stating exclusions (e.g. when to prefer patch_workflow or get_node_info over fetching the whole graph), so it is strong but 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 cover the safety profile (readOnlyHint=true, openWorldHint=false). The description adds useful behavior beyond that: results are ordered 'newest first' and scoped to clips the workflow can already read. It doesn't mention pagination or the limit ceiling, but the ordering and scoping context is genuine added value.

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 what the tool returns, then when to call it, then how to use the result. Zero filler and no repetition of schema content.

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 annotations carry the safety profile. The description covers the call trigger and downstream usage well; the only mild gap is not naming the complementary upload sibling for 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 coverage is 100%, so workflow_id and limit are already fully documented in the schema. The description adds no parameter-level syntax or format detail, so the baseline 3 applies even though it contextualizes why the tool is called.

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

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

States a specific verb (list) and resource (audio clips a workflow can already read) with ordering ('newest first'). This clearly distinguishes it from upload_audio_file, finish_audio_upload, and list_script_files among its 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?

Gives a concrete trigger: call it after the user uploads in the browser to learn the upload_id, and explicitly warns never to guess one. It also explains the downstream step (pass upload_id as audio_upload_id). However, it does not name alternate tools such as upload_audio_file/finish_audio_upload as the complementary actions, leaving some routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds useful behavior about the no-filter fallback returning locales with counts, but it does not discuss pagination or other operational details beyond what the schema provides.

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 written sentences with the resource and filtering modes front-loaded. No sentence is wasted and the fallback behavior is stated clearly.

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 100% schema coverage, an output schema, and read-only annotations, the description covers the key invocation modes and the no-filter fallback. Pagination and word-search semantics are left to the schema, which is acceptable here.

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 parameters like limit, locale, offset, and search are already documented. The description reinforces how locale and search shape results and what happens when both are omitted, but it does not add materially 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 and resource: lists workspace pronunciation dictionary entries with IPA and category. It clearly covers locale-scoped and search-based modes, though it does not explicitly name sibling tools such as preview_pronunciation or suggest_pronunciations.

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?

Explains the locale and search modes and the neither-filter fallback to a locale list with counts. It gives invocation context but does not explicitly say when to choose this tool over related siblings like preview_pronunciation or suggest_pronunciations.

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 and openWorldHint=false, so safety is covered. The description adds real behavioral context: the two distinct result shapes (provider+model count vs. model+voice count) and where voice data actually lives. It omits pagination or catalog-size caveats, so not a 5.

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

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

Front-loads the resource identity, then splits the two modes into parallel clauses with zero filler. The find_voices pointer is placed last where it is most useful as a routing note.

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 not the description's burden. For a single-optional-parameter read tool, the description covers purpose, both modes, and sibling routing, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100% and the parameter's schema description ('Omit to list every provider first') already conveys the same omit-vs-supply semantics as the description. The description adds no syntax or format detail beyond the schema, so 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 (list) and resource (speech providers, or one provider's models), and explicitly demarcates scope against the sibling find_voices ('Voices themselves come from find_voices'). An agent can distinguish this from find_voices 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?

Explains both invocation modes: no argument returns every provider with model counts, and supplying a provider returns that provider's models. It also routes voice lookups to find_voices. There is no explicit when-not guidance beyond that routing, so it falls 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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the useful behavioral fact that results are ordered newest first, which the structured fields don't convey; the enumerated return fields are redundant given an output schema exists.

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

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

Three tight sentences, front-loaded with purpose and ordering, then the two use cases. No filler and nothing misplaced.

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 readOnly annotation covering safety and an output schema covering return values, the description supplies exactly the missing pieces: ordering and the conditions that select this tool over its siblings. Nothing an agent needs to call it correctly is absent.

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 itself carries strong guidance ('Never invent one', 'Raise it only if the user asked for more'). The description adds no parameter meaning beyond this, 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 (list the recent runs of one workflow) plus a scope qualifier (newest first). It implicitly separates itself from single-run siblings like get_run_status by being a listing tool, but never names an alternative, 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?

Gives two concrete trigger conditions: recovering a lost run_id that run_workflow returned, and checking whether a run is still in flight before starting another. Clear context for when to reach for it, though it names no explicit alternative or exclusion.

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 and openWorldHint=false, so safety is covered. The description adds behavior the annotations and schema do not: newest-first ordering and the directive "never guess" an upload_id. That is meaningful added context beyond the structured fields, though it omits anything about paging 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?

Three short sentences, front-loaded with the identity of the resource, then the trigger, then the row contents. No padding or redundancy; 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 not be spelled out, and annotations already cover the safety profile. The description supplies the one thing neither structured field provides — when to call it and why — so an agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (workflow_id sourced from list_workflows, limit meaning). The description reinforces the upload_id/workflow_id correctness rule but adds no syntax or format detail beyond what the schema carries, 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 and resource ("The script files a workflow can already read") plus an ordering guarantee ("newest first"). It distinguishes itself from the upload siblings by framing the files as things the workflow has *already* been given, rather than a generic file listing.

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

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

Gives an explicit trigger: "Call it after the user uploads one in the browser, to learn its upload_id." That is clear when-to-use context with a stated goal. It stops short of naming an alternative or a when-not condition, so it is strong but not 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a genuine behavioral trait — templates are non-binding suggestions requiring user confirmation before cloning — but the enumerated return fields duplicate the existing output schema rather than adding context.

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 opening clause is well front-loaded, but the second sentence is a run-on mixing clone-vs-build guidance with a tangential aside about audio requests. The return-field enumeration is padding given the 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?

For a read-only, 3-parameter list tool with a full output schema and complete annotation coverage, the description supplies adequate context: what the gallery is, and what to do with the results. The redundant return-field list is a minor blemish rather than 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?

Schema coverage is 100%, so limit, search, and category are fully documented in the schema, including the 'raise it only if the user asked for more' and 'omit unless the user named a field of work' guidance. The description contributes nothing beyond that 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?

States a specific verb and resource ('Browse the template gallery — ready-made workflows') and implies a boundary against create_workflow_from_template by framing entries as suggestions rather than committed artifacts. It is clear what the tool returns, though the sibling differentiation is implicit rather than named.

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 downstream usage guidance ('tell the user which one would fit and ask whether to clone it or build a new workflow') and one odd exclusion ('asking for audio is not choosing a template'), but never states plainly when to call this versus list_workflows or create_workflow_from_intent. Usage is implied rather than specified.

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 and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: result ordering (most recently updated first), the fact that workflow_ids are only obtainable here, and the returned field set.

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-loads the core action, then the usage directive, then the ID-provenance rule, then the return fields — each sentence does distinct work 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?

An output schema exists, yet the description still names the returned fields, and it covers the ordering and the downstream workflow_id dependency. Nothing an agent needs to invoke this correctly is missing; only pagination nuance is left entirely to the 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 description coverage is 100% and both params (limit, search) are documented in the schema with usage cues like 'Raise it only if the user asked for more.' The description adds no parameter meaning beyond what the schema already carries, 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 and resource ('List this workspace's workflows') plus an ordering guarantee ('most recently updated first'). This cleanly separates it from get_workflow (single fetch) and list_templates (templates, not workspace workflows).

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 directional guidance: 'Check here before building anything new' tells the agent when to call it, and 'Every workflow_id another tool needs comes from here; never guess one' states a hard precondition for downstream tools. It stops short of naming an explicit alternative or exclusion, so it is strong but not 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds that the result includes the current selection state, a useful behavioral detail, but nothing about ordering, size, or other traits.

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 that covers both the resource and the selection state 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?

An output schema exists, so return structure need not be explained, and a zero-parameter read-only tool has few remaining gaps. Only the relationship to select_workspace 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 there is nothing for the description to disambiguate; the baseline for a no-param tool 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 (List) and resource (workspaces) plus the returned scope ('the workspaces you can work in'). It implicitly contrasts with select_workspace via 'which one is currently selected', but does not name the sibling outright.

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 mention of the 'currently selected' workspace hints at the read-then-select workflow with select_workspace, but there is no explicit when-to-use or when-not-to-use guidance, and no prerequisites are stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the description doesn't need to restate safety. It still adds real behavior: partial-edit semantics, the two-phase confirm/edit_token approval flow with the same patch, and the refusal of voice_map in favor of set_workflow_voice. It never characterizes what removal actually destroys or that all operations are atomic — that detail lives only in the 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?

Front-loads the core idea and the sibling disambiguation in two short paragraphs. 'Everything the operations skip is kept' slightly duplicates the schema's 'Anything they do not name is kept', and the trailing 'Voices: set_workflow_voice' fragment is terse but earns its place as a redirect.

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 schema, full annotation coverage and an output schema, the description covers the remaining model-facing decisions: patch vs full update, the confirm/token handshake, and the voice exclusion. Only operational limits (max operations, ordering, all-or-nothing application) are left to the schema, which is acceptable given its depth.

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 confirm, edit_token, workflow_id and patch are all documented in-schema; the description only reinforces patch semantics and the token round-trip. It adds no syntax or constraint detail (e.g. the 200-operation cap) beyond what the schema already says, so baseline 3 is right.

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 ('Change part of a saved workflow') plus the defining property of a patch — untouched state is preserved. It names the sibling it replaces (update_workflow) so the agent can separate the two 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?

Explicitly routes ordinary edits (threshold, config key, node add/remove, connection redraw) here rather than to update_workflow, and gives concrete example edits. It also states the required call sequence (unconfirmed call for an edit_token, then repeat with confirm=true) and where voice changes belong instead.

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

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

Beyond readOnlyHint=true and openWorldHint=false, the description adds a genuinely useful behavioral trait: the returned WAV link is short-lived, telling the agent to consume it promptly rather than store it. It also bounds the operation to a single string, which sets cost/latency expectations. It does not mention voice availability failures or locale fallback, so it stops short of 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?

Two short sentences with zero redundancy: the action and its output first, then the usage constraint. Nothing needs to be read twice and nothing 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 and annotations cover safety, so the description only had to supply intent plus the ephemeral-link caveat, which it does. The residual gap is the absence of any pointer to preview_voice for the adjacent case, which a low-complexity two-parameter tool can mostly survive without.

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%: 'ipa' is documented as 'exactly as it would be saved' and 'locale' as the BCP-47 voice selector, both richer than anything in the description. The only added semantics is the one-string-per-call cardinality, which is worth something but is the baseline expectation when the schema already does the work.

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+resource: it speaks one IPA string and returns a short-lived WAV link for auditioning before saving. That distinguishes it from mutation siblings like save_dictionary_entry, but it never names preview_voice, the closest sibling, so the agent must infer the split (voice sample vs. IPA string) on its own.

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

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

'One string per call, and only one the user asked to hear' gives a real constraint on how much to preview, implicitly discouraging bulk calls. However, there is no explicit statement of when to reach for this instead of preview_voice or suggest_pronunciations, so the routing decision is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: it does not search, one call returns one voice, and there is a soft cap of three previews. It stops short of stating latency/rate behavior, so a 4 rather than 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?

Front-loads the key constraint (one voice per call) and is appropriately short. Slight redundancy between 'call once per candidate, up to three' and 'one call answers with one voice' costs it the top mark.

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 supplies the usage pattern and the source-tool linkage, so an agent has what it needs; only minor behavioral detail (e.g. what playback entails) is absent.

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 explains that language is a family or locale derived from find_voices' preview_locales and that catalog_voice_id must match exactly. The description's restatement of the family/locale format adds no meaning 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 ('Play') and resource ('ONE voice'), and immediately distinguishes itself from the sibling find_voices by declaring 'This tool does not search.' An agent can tell exactly what this does versus the search tool.

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

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

Explicitly names the workflow: call once per find_voices candidate, up to three times, repeat so the user can compare and choose. The source (find_voices) and the intended iteration pattern are spelled out, leaving nothing to inference.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description is consistent with both — it is a read of a closed, Onepin-owned corpus. Beyond that it discloses the retrieval mechanism (questions are matched against English page descriptions) and the grounding obligation, which the annotations do not 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 resource and purpose, then a compact topic list, then the two behavioral rules. Every sentence earns its place, with only minor redundancy between the trailing sentence and the schema's parameter description.

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 single required parameter, a 100%-covered schema, and an output schema that carries return-value detail, the description supplies what is needed: scope, topic coverage, matching behavior, and grounding rules. Only minor operational details (repeated calls, result-size handling) are absent.

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 baseline is 3. The description's guidance — pass a short English restatement, matched against English page descriptions — largely restates the schema's own parameter description rather than adding new semantics, so it does not exceed the 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?

The description states a specific resource — the official Onepin documentation pages — and the operation (answering a question about the service), then enumerates the covered topics (plans and credits, runs and downloads, dictionary, templates, API). It is clearly distinct from every sibling, all of which operate on workflows, runs, or voices rather than documentation. The verb is implied by the tool name rather than stated, which keeps it from a full 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 gives usable context for when to reach for it (any question about what Onepin does) and a grounding constraint, 'Answer only from what it returns,' that tells the agent not to supplement from its own knowledge. No explicit when-not or alternative tool is named, but no sibling covers documentation, so there is little to exclude.

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 non-idempotent, but the description adds the crucial non-obvious behavior: this spends credits and must not be confirmed until the user approves the cost. That is real context beyond the annotation flags. It stops short of stating failure modes (e.g. what happens if the token expires or the script_text mismatches).

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 purpose and the cost consequence, then the confirmation protocol, then the follow-up. Every sentence carries an actionable constraint; no filler or restatement of the title.

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

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

For a 7-parameter, credit-spending, destructive operation with an output schema, the description covers the gates (token, confirm), the cost risk, and the next step. Return values need not be detailed since an output schema exists.

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; the description goes slightly further by tying run_token and script_text to estimate_run and stressing they must be the SAME text across both calls. Remaining parameters (dictionary_mode, source_language, dictionary_entry_ids) are left to the schema, which is adequate given full 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?

Opens with a specific verb+resource ("Start a run") and immediately distinguishes itself from estimate_run (price check) and get_run_status (polling), both named explicitly. An agent can route between these three 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?

States the prerequisite (estimate_run's run_token plus the identical script_text) and the full two-call sequence: without confirm=true nothing starts and only the price is returned; call again with confirm=true after the user agrees. It also names the follow-up tool (get_run_status) for polling.

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, idempotentHint=true, and readOnlyHint=false. The description adds useful context about omitted fields remaining unchanged and clear erasing selected fields, plus the IPA storage constraint. It does not cover permissions or broader side effects, so a 4.

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 no waste. The add/edit distinction is front-loaded, followed by the important edit and clear semantics.

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 rich annotations, full schema coverage, and an output schema, the description supplies the core behavior an agent needs. It omits explicit add-time required fields and the source of entry_id, though those are covered by the 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 description coverage is 100%, so the schema already documents every parameter thoroughly. The description restates key fields and adds the IPA-choice constraint, but does not provide much 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 and resource: add or edit a dictionary entry, with entry_id selecting edit mode. This clearly distinguishes the tool from siblings like delete_dictionary_entry and list_dictionary_entries.

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?

Explains the add-vs-edit decision via entry_id and clarifies edit semantics: omitted fields stay unchanged and clear erases fields. It does not name sibling alternatives or explicitly say when not to use it, so not 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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the result set is bounded by the script's content rather than dictionary size, so output stays short regardless of dictionary size, and that runs apply all entries by default. It says nothing about authorization, locale fallback behavior, or performance characteristics.

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 with no filler; the core behavior and the size guarantee are front-loaded before the run-related note. 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?

With an output schema present, return values need not be explained, and both parameters are fully documented in the schema. The safety profile is covered by annotations. Only the missing guidance about when to choose this over pronunciation-preview siblings 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?

Schema description coverage is 100% — both script_text ('as it would be run') and locale ('BCP-47, case-insensitive') are documented in the schema. The description adds no syntax, format, or locale-matching nuance 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?

The description states a concrete operation — determining which of the workspace's dictionary entries a given script contains and their frequencies — which is a specific verb+resource combination. It implicitly differentiates itself from list_dictionary_entries by noting the result is 'sized by the script, not by the dictionary.' The colloquial verb 'says' is slightly imprecise but the intent is unambiguous.

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

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

Usage is only implied: 'A run applies all of them by default' hints at the relationship to run_workflow, and 'sized by the script, not by the dictionary' hints at when to prefer this over list_dictionary_entries. But no sibling tool is named and there is no explicit when-to-use/when-not guidance, e.g. versus suggest_pronunciations or preview_pronunciation.

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 idempotentHint=true and destructiveHint=false, and the description adds a genuinely behavioral fact beyond them: the selection is 'remembered across sessions,' i.e. it mutates persistent state rather than being a per-call scoping argument. It stops short of saying how to inspect or clear the current selection.

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, zero filler, with the cross-tool scoping effect front-loaded and the persistence note second. Nothing to trim.

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

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

An output schema exists, so return values need no explanation. Purpose, single-parameter sourcing, and cross-session persistence are all covered, though interaction with concurrent sessions or how the selection interacts with tools that accept their own workspace argument is unstated.

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?

One parameter with 100% schema description coverage; the schema already tells the agent to supply 'the workspace_id from list_workspaces.' The description adds nothing about the identifier format or source beyond that, so the schema 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 ('select') and resource ('workspace') and adds the crucial scoping effect: it determines which workspace 'the other tools act in.' That distinguishes it from list_workspaces, which merely enumerates them, so an agent can route correctly 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?

The phrase 'which workspace the other tools act in' implies this tool should be called before other operations, which is useful implicit guidance. However, it never states when not to call it, whether it is required, or what happens if it is skipped, and no alternative is named.

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

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

Annotations cover the safety profile (destructive, idempotent, not read-only). The description adds real context the annotations don't: ambiguity returns candidates rather than guessing, last write wins, existing runs unchanged, and re-running re-charges credits. The credit-charging on re-run is particularly valuable since the agent might assume idempotency means 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 the core action, followed by exactly two sentences that each earn their place: the ambiguity-resolution workflow and the side-effect warnings. 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 mutation tool with destructive annotations and an output schema (which handles return values), this covers what the agent needs: how ambiguity is handled, what state is affected, and cost implications. Could say more about what 'pin' does to the node's existing configuration, but the essentials are there.

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 documents all four parameters well. The description reinforces the omission pattern for locale/model (only pass them when the tool asked for them via candidates) but doesn't add syntax or format details 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?

States a specific verb and resource: 'Pin a catalog voice onto one locale of a workflow's generator node.' An agent can immediately tell this differs from siblings like preview_voice, find_voices, or patch_workflow.

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 conditional: if a locale/model/generator is ambiguous, the tool returns candidates and you call again with that argument. This is actionable. It doesn't explicitly state when not to use it vs. preview_voice, but the write-vs-preview distinction is 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 readOnlyHint=true, so safety is covered. The description adds genuine value beyond that: 'Saves nothing' explicitly confirms non-persistence, and it enumerates the supported locales, which the annotations do not convey. Return format 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 short sentences, front-loaded with the core purpose, then the non-persistence note and supported locales. No filler; 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 not be explained, and annotations cover the safety profile. The description covers purpose, non-persistence, and locale constraints, leaving only sibling differentiation as a minor 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%, so the baseline is 3, and the description exceeds it by enumerating the actual supported locale values (en-us, ko-kr, etc.) rather than the vague 'such as ko-kr or en-us' in the schema. It adds a real constraint on the locale parameter.

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

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

States a specific verb+resource: it returns IPA candidates for a word. The phrase 'for the user to choose between' and 'differ on purpose and are not ranked' clarifies the intent well. It does not explicitly distinguish itself from the sibling preview_pronunciation, which limits it below 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?

'For the user to choose between' implies this is a suggestion step before selection, and 'Saves nothing' signals it is non-persistent. However, it never names alternatives such as preview_pronunciation or save_dictionary_entry, so when-to-use versus siblings 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?

Beyond the destructiveHint=true/idempotentHint=true annotations, it discloses the two-phase confirm protocol: an unconfirmed call writes nothing and returns the diff plus an edit_token required by confirm=true. That is substantial behavioral context (dry-run semantics, token dependency) the annotations do not 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?

Purpose is front-loaded in one sentence, followed by a tight procedural paragraph. Every sentence carries load (read source, validate, dry-run, then confirm), with no filler or repetition.

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, nested-object mutation with an output schema, the description covers the required pre-steps, the token chain, and the confirm safety gate, so an agent has everything needed to invoke it correctly. Return values are 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 cross-parameter meaning by chaining the params: the edit_token comes from this tool's own unconfirmed reply and confirm=true requires it, and it clarifies what the confirm=false default does. This ties the individually-documented fields into a coherent flow.

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?

"Replace an existing workflow's graph with an edited definition" is a precise verb+resource+scope statement, so the agent knows this is a full-graph replacement rather than a mutation. It does not explicitly contrast with the sibling patch_workflow, so the replace-vs-patch distinction is left implicit.

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 lays out an explicit ordered workflow: read the current graph with get_workflow(include_definition=true), edit, then validate_workflow_definition for the token, then call without confirm first. The condition selecting the safe vs destructive call is spelled out, and alternative tools are named.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive, closed-world write. The description adds behavior annotations cannot express: the first call is a no-op discovery step and the actual method choice belongs to the USER, which is exactly the kind of non-obvious trait an agent needs. It stops short of explaining what each method actually does (e.g. whether `agent` returns an upload target).

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 paragraphs, front-loaded with the purpose and then the call sequence in order; every sentence carries the protocol. Slightly awkward line breaks and the parenthetical format list are the only mild inefficiencies.

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 tool is a simple 3-param, zero-required handshake with an output schema (so return shape need not be described) and annotations covering the safety profile. Given that support, the description supplies everything an agent needs to call it correctly: what it does, the two-phase invocation, and that the choice is the user's.

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 already documented inline, including the enum values and the 'omit to get both options' default. The description reiterates the `method` handshake but adds nothing about `filename` or `workflow_id` (e.g. the browser-required workflow link) 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 concrete verb+resource ('Get an audio file into Onepin'), names the accepted formats, and ties the result to a 'source_audio node', so the agent knows the artifact and its downstream consumer. It does not explicitly distinguish this from the adjacent `finish_audio_upload` / `upload_script_file` siblings, which keeps it 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 an explicit call protocol: invoke with no `method` first (uploads nothing, returns the two options), then re-invoke with the user's choice. That is clear when-to-use guidance and prevents a premature upload. It offers no exclusions or named alternatives among the many sibling upload/list tools, so it stops at 4.

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 the non-destructive, non-read-only, non-idempotent profile, and the description adds genuinely non-obvious behavior: a no-method call performs no upload and instead returns the two options for the user to pick. It still doesn't say what the second call returns or whether a follow-up step is required after the chosen method.

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 purpose and followed by the round-trip protocol; nothing is padded. The phrasing 'Get ... into' is slightly conversational where a plainer verb would be tighter, but it is not wasteful.

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

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

An output schema exists so return values need no explanation, and the two-step interaction is spelled out. The remaining gap is the relationship to finish_script_upload and whether the flow truly ends after the chosen method, given the description mentions 'two ways' while the enum exposes three values.

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 documents the method-omission semantics ('Omit it to be given both options') and the .pdf example for filename. The description's '.txt or .pdf' constraint adds only marginal meaning beyond that, so the baseline of 3 is appropriate.

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

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

The description names the resource ('script file (.txt or .pdf)') and its destination ('into Onepin for a workflow to read'), which is more specific than the title alone. It does not, however, differentiate itself from near-name siblings such as finish_script_upload or list_script_files, leaving the agent to infer the boundary between them.

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 an explicit call protocol: invoke with no method first to get the options, then invoke again with the chosen method, and it names the human actor ('for the USER to choose'). It stops short of stating when this tool is appropriate versus the related finish_script_upload sibling.

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 say readOnlyHint/openWorldHint; the description adds far more: nothing is persisted, success yields a token that expires in 10 minutes and is byte-bound, and failures return per-error workarounds. That is exactly the side-effect and lifecycle detail an agent needs and cannot get from the annotations.

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

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

Two short paragraphs, front-loaded with the action and the no-persistence caveat, then the success/failure contract. No filler sentences.

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 single-param, nested-object tool with an output schema and readOnly annotations, the description covers the remaining unknowns: what it does and doesn't persist, what success returns, the token's lifetime and binding, and the failure error shape.

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 semantics: the definition passed must be the exact bytes you intend to create, since the token is bound to them. It also names get_node_info indirectly via the schema for building the graph.

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 ('check a workflow definition') and immediately scopes it: it applies the same gates a run start applies and 'Saves nothing'. This cleanly separates it from create_workflow and run_workflow, which do persist or execute.

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 ties the tool to its successor: the success token is what 'create_workflow requires', and 'validate what you will create' tells the agent to run this before creating. It stops short of an explicit when-not-to-use statement (e.g., that it is unnecessary for an already-validated or fetched definition), so it's clear context but not full routing.

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