ZeroWidth Workbench

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

Annotations already declare write, non-destructive, closed-world behavior, so the baseline is set. The description adds genuine behavioral context: the mention path 'rings their notification bell', which is a side effect an agent should know about, plus the thread-vs-reply branching. It stops short of noting auth requirements or idempotency.

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

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

Three sentences, front-loaded with the core action and mode selection before the usage example. The closing etiquette line ('never mention someone who didn't ask') is editorializing but arguably still useful guardrail 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?

For a write tool with no output schema and annotations covering safety, the description covers purpose, use case, thread/reply behavior, and mention side effects. Missing pieces are minor (approvalId meaning, mention limits, what a successful post returns).

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 only 43%, so the description is expected to compensate. It meaningfully explains mentionedUserIds (workspace member ids) and rootId (reply target), but leaves approvalId, workspace, entityKind semantics, and body constraints unexplained. Partial compensation warrants a 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+resource ('Posts a comment on a workspace entity') and clarifies the two modes — new thread vs reply when rootId is given. An agent can immediately tell what this does 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?

Gives concrete use cases ('leave findings where the discussion already lives', 'a summary on a long thread') that establish when to reach for it. It does not, however, distinguish this from siblings comments_list or comments_resolve, nor state any when-not conditions.

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 the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, and the description still adds real behavioral content: result ordering (open first, then resolved) and the fact that authors and timestamps are included. It stops short of stating pagination, volume limits, or behavior for entities with no threads.

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, front-loaded with the operative fact (what is listed, in what order) before the advisory second sentence. The second sentence is slightly rhetorical ("where disagreement lives before it becomes a decision") but it does convey routing intent, so little is wasted.

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

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

With no output schema, the description compensates by naming the returned content (threads, authors, timestamps, ordering), which is the key information an agent needs. It remains silent on result size/pagination and on empty-result behavior, so it is strong but not fully complete.

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

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

Schema coverage is 67%: workspace is well documented in the schema, entityKind has only a terse "What the thread hangs on" description, and entityId has none. The description says only "one workspace entity," adding no format, valid-value, or relationship detail beyond the schema enum, so a 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 concrete verb and resource ("Lists the comment threads on one workspace entity") and adds ordering detail (open first, then resolved). It implicitly separates itself from the write-side siblings comments_create and comments_resolve through the read verb, but never names or contrasts with them outright, so sibling differentiation is inferred rather than stated.

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?

"Read this before weighing in on contested work" gives a thematic when-to-use cue, which is more than nothing. However, no alternatives are named (notably comments_resolve or comments_create, the natural next/previous steps) and there is no when-not-to-use guidance or note on whether resolved threads can be filtered out.

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 flag this as a non-read-only, destructive mutation. The description adds meaningful policy context beyond that: the operation is a reversible toggle (resolve/reopen), and there is a sequencing constraint requiring justification before resolving. It does not state permission/auth requirements or what happens to existing replies, so it stops short of full disclosure.

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

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

Two dense sentences with the mechanical fact (what rootId is) front-loaded, followed by the policy. No filler, no 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 4-parameter mutation tool with no output schema, the description covers purpose, when-to-use, and the key parameter. The gaps are approvalId (never explained) and workspace/auth expectations, which matter for a destructive operation, but the core agent decision-making path is well served.

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 only 25%, so the description must carry more weight. It usefully defines rootId (the thread's root comment id) and implies resolved=true/false via 'resolve or reopen', but says nothing about workspace (which the schema does describe) or approvalId (undocumented in both places). Partial compensation for a low-coverage schema.

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

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

The description states a specific verb (sets the resolved state) and resource (a comment thread), and clarifies the ambiguous rootId by equating it to the thread's root comment id. It clearly covers both directions of the operation (resolve and reopen). It does not explicitly distinguish itself from comments_create/comments_list, though the reply-first instruction implies a division of labor.

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 when-to-use rules: resolve only when the human asked or the question is demonstrably settled, and reopen only for new evidence. It also imposes a prerequisite workflow step ('say what settled it in a reply first'), which implicitly routes the agent to comments_create. This is about as prescriptive as usage guidance gets.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-annotation behavior: result ordering ('most-used first') and the fields returned in each mode (tag name + count; kind, id, title, path), but says nothing about result limits or pagination.

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

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

Three sentences, front-loaded with the two modes that matter most before the usage advice. It is efficient, though 'the vocabulary the team already organizes by' is slight editorial padding for an agent-facing definition.

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

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

With no output schema, the description carries the return-shape burden and does so for both modes, which is the key gap an agent would otherwise face. It omits pagination/size limits, the only remaining incompleteness for a browse tool.

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

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

Schema coverage is 100%, so baseline is 3, and the schema already documents omitting the tag. The description goes beyond that by spelling out what each mode actually produces, which clarifies the semantics of the tag parameter's presence/absence rather than just restating it.

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 and separates the two operating modes: no tag lists all workspace tags with usage counts, a tag expands to all items filed under it across every tool. That mode split makes it trivially distinguishable from entity_tags_get and entity_tags_set.

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 concrete usage triggers: 'reuse existing labels instead of inventing near-duplicates' and answering 'show me everything about X' when X is a label. It stops short of naming alternatives (entity_tags_get, search_workspace) or stating when not to use it, so it is clear context without explicit routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are batch-scoped to one entityKind and 'Entities the user can't see are omitted', i.e. permission-based filtering of results. It does not describe pagination or the shape of the returned tag 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?

Three tightly packed sentences, front-loaded with the return value before the usage guidance. The gloss 'the labels galleries organize by' earns its place by disambiguating 'tags' in this domain. Slightly dense but 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?

No output schema exists, so the description carries the burden of describing the return, which it does at a high level ('returns the tags on a batch of entities'). Combined with the permission-omission note and the id-sourcing guidance, an agent has enough to call it correctly, though the exact tag object shape remains unspecified.

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 67%: workspace and entityKind are documented in the schema, but ids is not. The description compensates by explaining where ids come from (the kind's list/get tool or search_workspace) and that they belong to a single kind, which is the key constraint linking ids and entityKind. It does not mention the 100-item batch ceiling, which the schema already enforces.

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 ('Returns the tags on a batch of entities of one kind') and immediately distinguishes itself from entity_tags_set, which it names explicitly. An agent can tell it apart from the sibling tag tools 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 strong context: ids come from the kind's list/get tool or from search_workspace, and it should be run before entity_tags_set so the full set is replaced knowingly. It also frames a concrete question it answers ('what is this filed under'). It stops short of naming when NOT to use it versus entity_tags_browse, so it is not a full when/when-not/alternative spec.

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, but the description adds the crucial nuance annotations cannot: that this is a full replacement rather than an append, that an empty list clears tags, and how to avoid accidental data loss by reading first. It also discloses the tag format constraints and workspace-vocabulary preference, which are real behavioral 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?

Three tight sentences, front-loaded with the destructive replacement semantic that matters most. Every sentence carries distinct, non-redundant information: replacement behavior, read-then-merge workflow, format/vocabulary rules, and id sourcing.

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

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

With no output schema, the description does not explain what the call returns (e.g. the resulting tag list), and it does not mention the needs_confirmation/approvalId flow that the schema implies for a destructive operation. Otherwise it is complete: mutation semantics, safety guidance, format constraints, and id sourcing are all covered.

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 only 40%, so the description must compensate, and it does so for the highest-risk parameter: tags format (lowercase/numbers/spaces/hyphens) and replace semantics. It also explains where entityId comes from. It does not explain entityKind's 20 enum values or workspace/approvalId semantics, which the schema carries on its own.

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

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

The opening clause 'Replaces the FULL tag set on one entity' gives an exact verb, resource, and scope, and the parenthetical '(an empty list clears it)' nails the edge case. It is clearly distinguished from the read-oriented siblings entity_tags_get and entity_tags_browse, which it names directly.

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

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

It explicitly states when and how to use it: read current tags with entity_tags_get first, merge, then pass the full list, and warns that the call is not additive. It also directs the agent to entity_tags_browse for vocabulary and to the kind's list/get tool or search_workspace for the id, 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two things beyond that: the return payload is the 'full Markdown body' (valuable because there is no output schema) and that no authentication is required. It does not discuss rate limits or caching, hence 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?

Three short sentences with no filler; the core action is front-loaded and the sequencing hint and auth note each carry distinct information. Nothing could be removed without losing 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?

For a single-parameter read tool with no output schema, the description supplies exactly the missing pieces: what is returned (full Markdown body), when to reach for it versus search, and the absence of an auth barrier. Nothing an agent needs 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?

Only one parameter, and the schema documents it at 100% coverage including accepted slug formats ('compass/api', '/compass/api', 'docs/compass/api'). The description adds nothing about the slug beyond restating it, 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 (fetch) and resource (full Markdown body of a docs page) plus the retrieval key (slug). An agent can immediately distinguish this from search_docs (search) and list_docs (enumerate) without opening any schema.

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

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

Explicitly positions itself in a workflow: 'Use this after search_docs when the user needs the complete content of a page,' which names the alternative and the condition that selects this tool. It does not mention list_docs as the other plausible sibling, so it stops just short of exhaustive routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: 'No authentication required.' It stops short of describing pagination or result shape, but that gap is minor for a simple read.

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, no filler, and the scoping/workflow guidance is front-loaded before the operational note about authentication.

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

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

With no output schema, the description does tell the agent what it will get conceptually (available pages, their slugs) and how it fits with get_doc. It omits return fields and pagination behavior, which an agent might want, but nothing prevents correct invocation.

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

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

Schema description coverage is 100% and the single optional 'product' parameter is already documented with the same example values in the schema. The description repeats the filter semantics and examples rather than adding new meaning, 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 ('Enumerate all available docs pages') with scope and an optional filter named upfront. It is clearly distinguishable from sibling reads like get_doc, list_posts, and search_docs.

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

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

Explicitly states the use case: 'discover what slugs exist before calling get_doc', which gives the agent a concrete workflow position. It names one downstream sibling but does not contrast against search_docs, which is the closest overlapping discovery tool.

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

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

Adds real value beyond the annotations by disclosing that no authentication is required and that the corpus is public — something readOnlyHint/openWorldHint do not convey. However, it says nothing about result ordering, pagination, or behavior when nothing matches, leaving meaningful behavioral gaps for a search tool.

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

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

Three short sentences, front-loaded with what it does, then return shape, then when to use it, then the auth fact. Zero 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 two-parameter read-only search with a fully described schema and annotations, this covers purpose, trigger conditions, return fields, and access requirements. Nothing an agent needs in order to call it 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 inline, so the schema carries the load. The description adds no syntax, ranking, or limit guidance beyond what is already structured; 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 (search ZeroWidth product documentation) and scopes the corpus precisely — public product docs, not workspace content — which separates it from siblings like search_workspace, workbench_kb_search, and compass_pages_search without opening any schema.

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

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

Explicitly enumerates the triggering conditions: questions about a named ZeroWidth product, API behavior, or policy. It never names an alternative tool or a when-not-to-use case, so it stops short of full routing guidance.

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

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

Although annotations already declare readOnly/non-destructive/closed-world, the description adds substantial behavior the annotations cannot express: AND-of-words matching across name, tags, folder names and body text, best-first ranking, per-hit fields (id, kind, path, folderPath, tags, snippet), recursive folderId scoping, and permission-based result filtering ('only what the user can see, and only kinds this token may read').

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

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

Purpose and the 'use it FIRST' rule are front-loaded, and every later sentence adds either query semantics, return shape, or id-chaining guidance. The long enumeration of object kinds is the one place it runs heavy, though it doubles as scope documentation.

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

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

With no output schema, the description supplies what an agent needs about results (fields, ranking, snippet meaning, using folderPath to say where a thing lives) and how to chain ids into workspace_files_read or the kind's *_get tool. Permissions, empty-result handling, and workspace/scope limits are all covered.

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 80%, but the description still adds real meaning: it explains what the q words are matched against (name, tags, parent folder names, inner text) and gives worked examples ('northwind sow' finds the SOW in the Northwind folder). It also clarifies folderId is recursive, matching the schema, and leaves well-documented kinds/limit/workspace to the schema.

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

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

Opens with a specific verb and scope: 'Finds anything in the workspace in one call', then enumerates the object kinds covered (files, folders, flows, shims, knowledge bases, tasks, pages, datasets, evals, rubrics, reviews, specs, sources, Ledger entries, Napkin artifacts). This clearly separates it from focused siblings like compass_pages_search, search_docs, workbench_kb_search, and rooms_search, which each cover one kind.

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 trigger condition: 'Use it FIRST whenever the user mentions something without saying where it lives', backed by three concrete user-phrase examples. It also gives a recovery procedure when results are empty ('try fewer or different words before telling the user it doesn't exist'), which is when-to-use guidance beyond the happy path.

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

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

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: node inputs/outputs are truncated for transport and the full record lives in the flow's dev drawer. That's an important expectation-setting detail for a read tool.

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

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

Front-loaded with what the tool returns, then the when-to-use trigger, then parameter selection, then the truncation caveat — each 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?

No output schema exists, and the description compensates well by describing the return shape (per-node timelines, inputs/outputs, errors) and its truncation limit. Combined with 100% schema coverage and read-only annotations, an agent has everything needed to call and interpret 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% — the schema already documents limit's default/max and its being ignored when executionId is set, plus the workspace auth nuance. The description's 'Pass executionId to inspect one run, or just flowId for the most recent runs' adds only marginal selection guidance beyond what the schema states, 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?

States a specific verb+resource (inspect a flow's executions) and enumerates exactly what comes back: per-node timelines, inputs, outputs, durations, and the failing error. This is clearly distinguishable from siblings like workbench_flows_get or workbench_flows_run, which manage or trigger flows rather than return execution traces.

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 — 'USE THIS when a run misbehaves instead of guessing' — and routes the agent to the follow-on tool (workbench_flows_edit_text) for fixing. It also clarifies executionId vs flowId selection. It lacks an explicit 'when not to use' or a comparison against trace-reading siblings, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description usefully adds that it is a preparation prerequisite and enumerates the specific rules and examples it contains, which is real behavioral context for an agent. It does not, however, describe output format or size, keeping it 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 dense sentences, front-loaded with the imperative 'READ THIS FIRST,' then a compact inventory of covered topics. Every clause earns its place; 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?

Given zero parameters, no output schema, and annotations that already carry the safety profile, the description supplies the essential detail an agent needs: when to consult it and what it teaches. Minor gap is the absence of any hint about the guide's own return shape, though that is not obligated without an 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?

Parameter count is zero, so the baseline is 4. No parameters need explaining and none are misrepresented; the description focuses entirely on content, which 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 resource (the flow-authoring guide / orchestration JSON format) and enumerates its exact contents (document shape, ports rule, link format, plugin links, worked examples). It is clearly distinguishable from sibling tools like workbench_flows_scaffold or workbench_node_catalog_get.

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

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

Explicitly states when to use it: 'READ THIS FIRST before writing or editing any raw flow orchestration JSON.' The trigger condition and sequencing are unambiguous, 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?

With annotations only declaring readOnly=false, destructive=false, this description carries real additional context: attaching an already-present KB is a no-op (idempotency), the operation may require a confirmation round-trip, and it describes the actual runtime effect on the model's tools and prompt. No contradiction with the annotation profile.

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

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

Front-loaded with the core action and its two behavioral modes, then workflow ordering. Slightly dense as one paragraph and the interface re-grant aside is a bit of a tangent, but no sentence is filler.

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

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

No output schema exists, yet the description surfaces the one return value that matters operationally (needs_confirmation) and pairs it with the approvalId parameter, plus precondition and ordering. An agent has everything needed to invoke 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 coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by explaining what the knowledgeBaseId choice entails (docs vs tabular behavior) and by tying approvalId to the needs_confirmation return. It stops short of describing workspace semantics, which the schema already handles well.

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 (attach a knowledge base to an AGENT flow's draft) and immediately explains the two distinct behaviors depending on KB type: docs KB becomes a search tool, tabular KB injects tables into the prompt plus a query tool. It distinguishes itself from siblings by naming workbench_flows_publish and workbench_flows_run, and from the workbench_kb_* family by scoping to flow attachment.

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 explicit sequencing: attach BEFORE publish, then try it with workbench_flows_run, then publish; plus the exception path (re-grant a newer version to anything pinning an older one, e.g. an interface grant). It also states a precondition (flow needs a system prompt, scaffold it) and multi-call mechanics (needs_confirmation / approvalId).

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 destructiveHint=true, but the description goes far beyond that: it enumerates the concrete cascade — schedules stop, share links die, evals can no longer run and show flowOk: false — and discloses the needs_confirmation return. This is exactly the destructive-side-effect context annotations cannot carry.

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

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

Front-loads the action, then the cascade effects, then the pre-check and alternative guidance, closing with the return caveat. Dense but every clause earns its place; 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 destructive, no-output-schema tool, the description supplies the cascade consequences, the two sibling pre-checks, the safer alternative, and the confirmation protocol. Nothing an agent needs to call this safely 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 flowId, workspace, and approvalId are already fully documented in the schema. The description adds the needs_confirmation/approvalId linkage in the return note but does not enrich the individual parameters. 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 (Deletes) and resource (a flow), and immediately distinguishes itself from the sibling workbench_flows_update by naming the archive alternative. An agent can tell this apart from workbench_flows_update and workbench_flows_schedules_delete without opening a schema.

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

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

Explicitly routes the agent: prefer workbench_flows_update with archived: true when the user just wants it 'out of the way', and points at caliper_flow_performance and workbench_flows_schedules_list to check before proposing. Names both the alternatives and the conditions selecting them.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation/safety profile is known. The description nonetheless adds real context beyond them: edits land on the draft only and publishing is a separate step, zero/multiple matches error rather than guess, and a `needs_confirmation` envelope may require showing a diff and waiting. That is useful behavioral detail layered on top of 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?

Front-loaded with the core action and edit-tool semantics. The sentence count is high, but nearly every sentence carries constraint or workflow info that isn't repeated elsewhere; the density is slightly sprawling but 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?

With no output schema and a mutation tool that can return a confirmation envelope, the description is complete enough for an agent to call it correctly: sourcing the find text, uniqueness constraints, draft-vs-published effects, and the approval/re-run loop are all covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: `find` must be exact text copied character-for-character from workbench_flows_get, must occur exactly once, is text inside a single value rather than JSON, with a concrete model-slug example. This goes beyond the schema's own parameter text and compensates for any inference an agent might otherwise make.

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: applies ONE precise text replacement to a flow's DRAFT orchestration. It is clearly distinguished from structural siblings like workbench_flows_update by explicitly saying it can't add or remove nodes or links.

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 explicit when-to-use context (the improvement primitive), the ordering of steps (check caliper_flow_performance, cite run id, apply after approval, re-run caliper_evals_run), and points to workbench_flows_get for sourcing the exact text. Alternatives and exclusions are both 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?

Beyond the annotations, it discloses meaningful behavior: the result is a draft owned by the user, forking consumes the plan's flow cap, and the call may return needs_confirmation (which the approvalId parameter then resolves). This is exactly the kind of mutation context an agent needs and that annotations alone 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?

Four tightly-packed sentences, front-loaded with the core action before constraints, provenance, cap cost, and the confirmation hint. Every sentence carries non-redundant information.

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

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

For a mutating tool with annotations covering the safety profile and a fully documented schema, this covers ownership, cost (flow cap), the confirmation branch, and the invalid-input case. Nothing an agent needs to call it correctly is missing.

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

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

With 100% schema description coverage the baseline is 3, but the description adds real value by clarifying the provenance of flowUuid and that forkedFromVersion optionally pins which published version is copied. It does not elaborate on workspace/approvalId semantics beyond the schema, keeping it at 4.

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

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

The description states a specific verb and resource — copying a PUBLIC flow from another workspace into this one as a new draft — plus the scope constraint (cross-workspace template). It is immediately distinguishable from siblings like workbench_flows_get, workbench_flows_list, and workbench_flows_update.

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 when-to-use (public flow from another workspace) and an explicit when-not ("Flows already in this workspace can't be forked — open them instead"), which routes the agent away from a misuse of this tool. It also points to where the required identifier comes from (public template pages and workbench_flows_get output).

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: what each view returns, that full is large, and the operational warning to copy `find` text character-for-character from the node view rather than from memory.

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 scope ('One flow') and then the routing guidance. Every clause carries actionable content — no filler, no repetition 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?

No output schema exists, so the description must describe returns, and it does: summary yields fields plus one line per node and links, node yields full settings and prompt, full yields the orchestration body. Workspace handling and error behavior live in the schema, so this is nearly complete, missing only edge-case caveats.

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 restates the view modes and the nodeId pairing, which the enum and property descriptions already document; it adds little parameter detail the schema doesn't already carry.

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

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

The opening 'One flow' plus the per-view breakdown makes clear this retrieves a single Workbench flow, and the view semantics (nodes/links, one node's settings, whole orchestration body) pin down what is returned. It reads as retrieval rather than a sibling like workbench_flows_list, but the verb is implied rather than stated, so it stops short of a crisp 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 prescribes exactly which view to use and when: default summary to pick a node, `view: node` + nodeId before workbench_flows_edit_text, `view: full` for the whole body. It names the dependent sibling (workbench_flows_edit_text) and the condition that selects this tool over it, 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 the safe read-only, non-destructive, closed-world profile, so the bar is lower; the description still adds real value by disclosing the visibility scoping (only flows the caller can see) and the summary-level nature of results. Pagination or result-limit behavior is not mentioned, which is the remaining gap.

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

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

Two tight sentences, zero filler. The scoping statement comes first and the routing hint second, which is the right front-loading order.

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

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

With no output schema, the description usefully names the returned fields (id, name, visibility, updatedAt) and points to the get tool for the full body, which covers the main agent questions. Only result-set size/pagination behavior is left unaddressed.

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

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

There is one parameter (`workspace`) whose schema description is fully detailed, covering token-type behavior and overrides. The description adds nothing about it, relying entirely on the schema. Baseline 3 is correct when schema coverage is 100%.

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 (Lists) and resource (every flow) with scope (active workspace the caller can see), and explicitly names the sibling `workbench_flows_get` as the detail counterpart. An agent can separate this discovery tool from the dozens of other workbench_flows_* siblings at a glance.

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 implies use this for enumeration and `workbench_flows_get` when the full orchestration body is needed, which is explicit alternative routing. It stops short of stating when-not to use it (e.g., when the id is already known) or any paging guidance, 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 flag destructive=true, but the description goes well past that: it explains that the draft keeps evolving while the published snapshot stays frozen, that publishing does NOT execute the flow, that runOnPublish evals spend credit, that refusal occurs for an untried draft, and that a `needs_confirmation` response is possible. These are exactly the side effects an agent must know before invoking a publish.

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

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

Front-loaded with the core action and effect, then prerequisites and side effects. Dense with parentheticals (e.g., the credit-spend aside) which slightly reduce scannability, but nearly every clause carries actionable information.

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

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

For a destructive, open-world mutation with no output schema, the description covers preconditions, non-obvious side effects, the confirmation flow, and the refusal path. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema, including note, untried, version retagging, workspace scoping, and approvalId. The description adds workflow context around `needs_confirmation` but does not explain the `untried` flag or version label semantics beyond what the schema already says. 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 and resource ('Snapshots the flow's current DRAFT as a named published version') and immediately clarifies the scope of what that version governs — schedules, share links, public-API runs, evals. An agent can distinguish this from workbench_flows_run, workbench_flows_update, and workbench_flows_schedule without opening any schema.

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

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

Explicitly names the precondition (draft must have been run since last change; otherwise refused), prescribes the alternative to try first ('workbench_flows_run on a few real questions, including one it should decline'), and notes the eval cost side effect. This is when/when-not/alternatives guidance in full.

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 destructiveHint=false, so safety is covered. The description adds real behavioral context the annotations cannot: newest-first ordering, and the semantic distinction between entries carrying a `version` label versus null-version draft autosaves. It stops short of describing page size or truncation behavior, which is a minor gap.

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

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

Two sentences, front-loaded with the return shape and ordering before the use cases. Every clause earns its place; nothing is repeated from the schema or annotations.

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

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

With no output schema, the description must carry the burden of explaining the return shape, and it does so for the key fields (version label, note, null-version drafts) and ordering. It leaves the remaining entry fields and result-size behavior implicit, so it is strong but not exhaustive.

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 interpretive value by explaining what a 'labeled published version' is, which is exactly what makes the publishedOnly flag meaningful. It says nothing extra about workspace or limit, so it is above baseline without being complete.

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 flow's revision history, newest first') and immediately scopes it to publish history, distinguishing it from siblings like workbench_flows_get and workbench_flows_list. An agent can tell what this returns without opening the schema.

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

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

Gives three explicit when-to-use cases — checking publish state, sourcing a revision id for caliper_evals_create's flowRevisionId, and seeing when the draft last changed — including a named sibling tool and the parameter it feeds. This is the strongest form of 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 declare readOnlyHint=false and openWorldHint=true but say nothing about cost; the description adds that it spends workspace LLM budget bounded by the token's cost cap and runs synchronously. That is genuine context beyond the structured fields, though side effects, idempotency, and the needs_confirmation/approval path are not surfaced here.

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

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

Three sentences, front-loaded with the core action before the source-selection and input-format details; every sentence carries information. Slightly dense in the final clause but no wasted text.

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 mutation with no output schema, it covers execution mode, source selection, cost implications, and input format. The main gap is that return values are only described as 'its outputs synchronously', leaving the response shape underspecified without an output schema to compensate.

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

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

With 100% schema description coverage the baseline is 3, but the description adds concrete meaning by giving example input envelope shapes ({"kind":"chat","messages":[…]} / {"kind":"form","values":{…}}) and clarifying the draft-vs-published default for source/version. This goes beyond restating the schema.

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

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

States a specific verb and resource ('Execute a flow and return its outputs synchronously'), which clearly separates it from read-style siblings like workbench_flows_get or workbench_flows_list. It does not explicitly name an alternative tool, so it falls short of the 5-level sibling differentiation, but the action 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?

The description explains that draft runs by default and that source:"published" (with optional version) runs the live version, which is useful conditional guidance. However, it never states when to prefer this over adjacent tools such as workbench_flows_schedules_run_now or caliper_evals_run, leaving usage primarily 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 only tell us this is a non-read-only, non-destructive, non-open-world write. The description adds real behavioral context beyond that: a possible `needs_confirmation` response requiring approvalId re-call, the fact that opportunityId is refused when a change already has a draft, and the returned editor path to surface to the user.

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 before branching into pattern choice, stubbing, user-facing path, approval flow, and next steps. Dense but nearly every sentence carries actionable instruction; slightly long and could be split, but 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 13-parameter creation tool with no output schema, the description covers the return semantics (editor path, needs_confirmation), the approval loop, the cross-tool link, and the follow-on tools. Nothing an agent needs to call it correctly appears 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, but the description adds cross-parameter workflow meaning the schema can't convey: approvalId is only for a re-call after needs_confirmation, and opportunityId creates the bidirectional Compass link. That is genuine value over the per-parameter schema text.

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

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

States a specific verb+resource ('Creates a runnable first-draft flow from a spec you author') and immediately scopes it against the update/create siblings by describing it as a first-draft generator. The pattern-selection guidance (classifier/structurer/agent/interviewer) further pins down exactly what kind of artifact is produced.

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 when-to-use guidance: 'classifier for read-and-bucket, structurer for transform/extract/draft-for-review, agent for genuinely conversational.' It also routes the agent forward to workbench_flows_run and workbench_flows_publish, and explains the needs_confirmation re-call path.

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

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

Annotations only declare write/non-destructive/openWorld=false, and the description adds meaningful behavioral context beyond them: the scenario surfaces in the test pane's Scenarios menu, Caliper evals can execute as it, and the call 'May return needs_confirmation' (matching the approvalId param). It stops short of explaining the confirmation round-trip in detail.

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 compact sentences, front-loaded with the core action, then downstream visibility and the sourcing/confirmation notes. No filler, though the sourcing instruction is somewhat tangential to invocation.

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 non-destructive write tool with no output schema, the description covers what gets created, where it surfaces, and the implicit confirmation step. Combined with the fully documented schema, an agent has enough to call it correctly; only the approval cycle could be spelled out further.

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 documents all five parameters richly (flowId, values, workspace, approvalId, scenarioName). The description paraphrases scenarioName/values but adds no syntax or format detail beyond what the schema already carries, 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: 'Saves a named scenario: values for the flow's variables,' and clarifies conceptually what a scenario is ('one demo customer'). It doesn't explicitly name its siblings (scenarios_update/list/delete), but the create intent is unmistakable.

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?

Offers real workflow guidance ('use the person's details from what the user shared... and say which ones you made up') but that is about sourcing values, not about when to choose this tool over scenarios_update or scenarios_list. Usage context is implied rather than an explicit when/when-not rule.

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

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

Although annotations already declare destructiveHint=true, the description adds real value beyond them: it discloses the side effect that a running design session reverts to no scenario, and it warns that the call may return needs_confirmation, implying a two-phase approval flow. It stops short of stating whether deletion is reversible or what happens to dependent data.

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 very short sentences, with the core action front-loaded and side effects following. The phrasing of the second sentence ('A design session running as it goes back to no scenario') is slightly awkward, but nothing is wasted.

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

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

For a destructive tool whose annotations already carry the safety profile and whose schema fully documents parameters, this covers the essentials: what is deleted, its effect on running sessions, and the confirmation return. Missing only reversibility/dependency details, which are minor gaps.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including approvalId's role in the confirmation flow. The description only loosely connects to those fields via 'needs_confirmation', 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?

States a specific verb and resource ("Deletes one scenario"), which cleanly distinguishes it from the sibling create/update/list scenario tools. It does not explicitly name the alternatives, but the delete action 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?

There is no guidance on when to delete versus update or reset a scenario, nor any prerequisites (e.g., required scope or workspace rules). The only contextual hint is the confirmation behavior, which is about execution mechanics rather than usage selection.

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, destructiveHint=false, openWorldHint=false), so the description only needs to add context. It does: it explains that variables are {{token}} placeholders in agent prompts with types, and that the read is a prerequisite for writes. It does not mention pagination or result size 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?

Two sentences, no filler. The content summary comes first and the usage instruction second, so the most actionable information is neither buried nor repeated.

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

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

No output schema exists, so the description carries the burden of describing returns — and it does, enumerating both halves of the payload (variables and scenarios with values). Combined with 100% schema coverage on inputs and clear annotations, an agent has everything needed 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 description coverage is 100% and both parameters (flowId, workspace) are fully documented in the schema, including workspace-token nuance. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

The description names the exact resource set returned: a flow's variables (with their {{token}} syntax and types) plus every saved scenario and its values. That is specific enough to distinguish it from the sibling scenarios_create/update/delete tools 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?

It gives an explicit precondition and ordering rule: 'Read this before creating or updating a scenario,' naming the alternatives by function. The agent knows both when to call it and which tools it must precede.

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

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

Annotations only declare the safety profile (destructiveHint=true, readOnlyHint=false). The description goes well beyond that with the critical merge semantics ('pass only the variables that change'), the null-clears-a-variable rule, and the fact that the call may return needs_confirmation, which explains why an approvalId parameter 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 short sentences, each carrying a distinct fact (what it does, how `values` behaves, where the id comes from, and the confirmation possibility). Zero padding and the key mutation semantics are front-loaded.

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

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

With 6 parameters covered 100% by the schema and no output schema, the description supplies the missing behavioral pieces (merge/clear semantics, confirmation flow) for a destructive mutation tool. It stops short of detailing what the response payload looks like on success, but nothing required to call it 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: that `values` merges rather than replaces and that a null value clears a variable. That materially changes how an agent should populate the nested object.

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 pair ('Renames ... or changes its values') against a clearly identified resource (a scenario), which cleanly separates it from the sibling create/delete/list scenario tools. An agent can identify exactly what this call mutates 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 gives one concrete prerequisite ('Get the scenarioId from workbench_flows_scenarios_list'), which is genuinely useful routing information. However, it never states when to prefer this over scenarios_create, or when a rename is inappropriate, so usage is implied rather than guided.

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 and destructiveHint=false, so the description only needs to add context, which it does: it discloses the hard prerequisite that the flow must be published, that each run uses the latest published revision with a fixed input envelope, and that output is routed per `delivery`. It omits the needs_confirmation/approval flow implied by the approvalId parameter, which is left entirely 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?

Front-loaded with purpose, then the when-to-use rule, then the prerequisite, then parameter guidance — a sensible order with no filler. It is dense and long, but nearly every clause carries operational meaning.

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 mutation tool with no output schema, the description covers what an agent needs to call it correctly: the required published state, sibling routing, and the semantics of the two required params. Gaps remain around the two scheduling modes (interval vs recurrence), delivery routing choices, and the approval-id confirmation loop.

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 55%, so the description must compensate, and it does for the important parameters: it explains that `input` is a fixed envelope matching workbench_flows_run's shape and that the flow should fetch time-varying data at run time, and that `delivery` routes output. It adds little for label, scheduleTime/scheduleTimezone/scheduleDayOfWeek, or the interval-vs-recurrence split beyond what the schema descriptions state.

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 ('Set a specific built flow to run automatically on a cadence') plus scope qualifiers (deterministic counterpart to a routine, runs the latest PUBLISHED revision). It explicitly distinguishes itself from routines_create and from the sibling schedule management tools.

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

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

Gives an explicit trigger ('USE THIS when the user wants a flow they've built to run on a schedule') with a concrete example, an explicit exclusion ('Do NOT create a routine for this'), and routes follow-up work to workbench_flows_schedules_list / _update and publish via workbench_flows_publish.

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, but the description adds non-structured traits: permanence ('for good') and the fact that the call may return `needs_confirmation`, implying a two-step approval flow. It does not spell out that the first call may not actually delete, but the confirmation hint is valuable context beyond 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?

Three short sentences, zero filler, with the destructive nature and the preferred alternative front-loaded before the return-value caveat.

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

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

For a destructive, non-open-world operation with no output schema and full annotation coverage, the description supplies the irreversibility warning, the safer alternative, and the confirmation flow. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so flowId, workspace, approvalId and scheduleId are all documented in the schema. The description only implicitly links needs_confirmation to approvalId, adding little meaning beyond what the schema provides; 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 and resource ('Removes a schedule for good') and immediately distinguishes itself from the sibling that is the safer alternative. An agent can route between delete and update 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 names the alternative (workbench_flows_schedules_update with enabled: false) and the condition that selects it ('when the user might want it back'). This is a clear when-not-to-use rule, which is exactly what a destructive tool needs.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by describing the returned fields (cadence, enabled flag, next fire time, delivery, last run status) and the read-before-write workflow, though it says nothing about pagination or auth requirements for large schedule sets.

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, front-loaded with what the tool returns and then the routing guidance. The field enumeration is somewhat dense but each item earns its place for an agent deciding whether this call answers its question.

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

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

No output schema exists, so the description carries the burden of describing return content, and it does so with concrete fields. Combined with the sequencing guidance for the schedule lifecycle, 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 description coverage is 100%, with flowId and workspace both documented in the schema, including the workspace-token nuance. The description adds no parameter-level meaning beyond 'one flow', 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 ('Every schedule on one flow') and enumerates what the listing contains (cadence, paused state, next fire time, delivery, last run status), which lets an agent distinguish it from workbench_flows_list, workbench_flows_schedule, and the other schedule tools without opening any schema.

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

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

Explicitly says when to call it: before workbench_flows_schedule to avoid creating a duplicate, and to obtain the scheduleId needed by workbench_flows_schedules_update, _delete, and _run_now. This is a precise when/when-not with named alternatives.

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

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

Goes well beyond the annotations: discloses that it spends workspace credit, delivers for real, sits behind an approval gate, may return needs_confirmation, and is fire-and-forget with specific follow-up tools named. This is exactly the behavioral context an agent needs before invoking a real-delivery side-effecting 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?

Dense but front-loaded: the core action comes first, followed by scope, cost/approval caveats, and follow-up. Every sentence carries distinct, actionable information 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?

No output schema exists, but the description compensates by telling the agent the run is fire-and-forget and naming workbench_flows_schedules_list (lastStatus) and workbench_executions_get (trace) as the way to observe results. Nothing material 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 all four parameters are already documented in the schema. The description's mention of the approval gate and needs_confirmation adds indirect context for approvalId, but it does not add syntax or format detail beyond the schema. 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 and resource ('Runs one iteration of a schedule immediately through the real scheduled pipeline') and pins the exact scope: same input, same delivery, no cadence change. This clearly distinguishes it from workbench_flows_run and workbench_flows_schedules_update.

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 says when to use it ('Use it to test a schedule the user just set up') and adds a useful edge case ('Works on paused schedules'). It stops short of naming the alternative tools (e.g., workbench_flows_run) or stating when NOT to use it, so it is clear context without full routing guidance.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuine behavioral value beyond that: pausing keeps configuration, resuming recomputes fire time from now, and 'May return needs_confirmation' warns of an approval round-trip. It doesn't explain what 'destructive' concretely means here, keeping it at 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?

Dense, front-loaded sentences with no filler; each clause maps a field or action to its effect. The prerequisite note and the needs_confirmation warning are placed at the end without burying the primary 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 13-parameter mutation tool with no output schema, the description covers the main behaviors, partial-update contract, prerequisite lookup, and the confirmation flow. Minor gaps (workspace/approvalId handling are left to schema) keep it just below full completeness.

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 62%, so structured fields do part of the work, but the description adds real meaning: enabled's pause/resume semantics, the cadence field group, and that label/delivery/input are also mutable. The recurrence/approval params are documented in-schema rather than the description, so not a 5.

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

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

States a specific verb (changes) and resource (one schedule), then enumerates exactly which fields do what: `enabled: false` pauses, `enabled: true` resumes, cadence fields re-time. An agent can distinguish it from `workbench_flows_schedule` (create) and `schedules_run_now` 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?

Gives clear operational context — 'Pass only what changes' establishes it as a partial-update tool, and 'Get the scheduleId from workbench_flows_schedules_list' routes the agent to the prerequisite tool. It does not explicitly contrast with sibling scheduling tools (create vs run_now), so not a full 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=false, destructiveHint=false, and openWorldHint=true, but the description adds substantial behavior: no-account guest access, /s/<token> page, latest-published-revision-only scoping, per-guest conversation caps, link expiration, and a possible needs_confirmation response. No contradiction with 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?

The description is front-loaded with the core action and then adds only necessary prerequisites, lifecycle context, and confirmation handling. Each sentence carries distinct operational value, and none is redundant 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?

For a mutation tool with no output schema, the description supplies the missing context an agent needs: required published state, share-link behavior, expiration, management siblings, and the needs_confirmation/approval flow. Annotations and schema cover safety and parameter details, so nothing critical 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 schema already documents all five parameters, including label, flowId, workspace, approvalId, and expiresInDays. The description reinforces the label/approval flow and published-revision requirement but does not add format or syntax detail beyond the schema, 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?

States a specific verb and resource: creates a no-account guest link for chatting with the flow's latest published revision. It distinguishes itself from related lifecycle tools by naming workbench_flows_shares_list, workbench_flows_shares_revoke, workbench_flows_revisions_list, and workbench_flows_publish.

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 when to use it ('fastest way to put a working flow in a stakeholder's hands') and gives a clear prerequisite: the flow must have a published version, with sibling tools named for checking or publishing. It does not state when not to use it or name an alternative create-sharing mechanism, but related lifecycle operations 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context beyond them: results are ordered newest first, and dead links are returned without a shareUrl, which an agent would otherwise misread as missing data. No pagination or permission notes, but the key behavioral quirk is disclosed.

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: the first leads with scope and ordering then enumerates returned fields, the second leads with the use cases. The parenthetical about dead links is the only aside and it carries necessary meaning.

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

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

With no output schema, the description is the sole source of return-shape information and it covers label, liveness, shareUrl, expiry and usage counts. Usage and the downstream revoke linkage are covered too; only edge details like pagination or an empty-list result are unaddressed.

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

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

Schema description coverage is 100% and both parameters (flowId, workspace) are documented in the schema, including the token/workspace-key nuance. The description adds nothing about parameter semantics, 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 ('Every guest link on one flow') and immediately scopes it to a single flow, distinguishing it from the workspace-level or flow-level siblings. It also names workbench_flows_shares_revoke, so an agent can place it relative to the share lifecycle without opening a schema.

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

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

Gives three concrete use cases ('who has access', recovering a lost link, obtaining the shareId for revoke), which is clear when-to-use guidance. It stops short of stating exclusions or explicitly contrasting with workbench_flows_share_create, 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 destructiveHint=true, but the description adds real context beyond them: the effect is immediate, existing holders lose access, prior conversations survive in the flow's history, and a needs_confirmation response may occur. That scoping of what is and is not destroyed is exactly the kind of disclosure 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?

Three short sentences, front-loaded with the consequence of the call, then persistence behavior, then the id source. No filler and nothing buried.

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

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

For a destructive 4-parameter tool with no output schema, the description covers the destructive scope, the confirmation path, and where to obtain the required id. Only minor gaps remain, such as reversibility or idempotency of a revoke, which an agent might want to know.

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 flowId, shareId, workspace, and approvalId are already documented, including the approvalId tie-in to needs_confirmation. The description repeats the shareId source but adds no format, constraint, or 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 and resource ('Kills one guest link immediately') and scopes it to a single link, which cleanly separates it from workbench_flows_shares_list and workbench_flows_share_create. 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 routes the agent to the prerequisite step by naming workbench_flows_shares_list as the source of shareId, which is genuine usage guidance. It does not, however, state any when-not-to-use condition or contrast with a sibling such as share_create, so it falls short of explicit alternative framing.

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 destructiveHint=true; the description goes further by explaining that archiving is non-destructive to operation (still runnable, scheduled, shared) and reversible via archived: false, plus surfaces the needs_confirmation/approvalId handshake. This is exactly the kind of behavior an agent cannot infer 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?

Four tight sentences with the scope constraint front-loaded, followed by the sibling exclusion, the archive semantics, and the confirmation caveat. No filler or redundancy.

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

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

For an 8-param mutation tool with no output schema, the description covers scope, alternatives, partial-update expectation, archive reversibility, and the confirmation flow. Workspace/auth details are already in the schema, so nothing an agent needs to invoke correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents partial-set semantics for tags, archived true/false, and workspace auth rules. The description restates the field list and 'pass only what changes' but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Names the concrete resource (a Workbench flow) and the exact metadata fields it mutates (name, description, visibility, tags, archived), then explicitly excludes orchestration content and points to workbench_flows_edit_text. An agent can distinguish it from that sibling 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?

States when to use this tool versus workbench_flows_edit_text, tells the caller to 'pass only what changes' (partial update), and gives the condition for restoring a flow (archived: false). Alternative-routing and exclusions are both explicit.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds crucial context beyond them: ingestion runs in the background and returns a runId, embedding spends workspace inference credit, the call may return `needs_confirmation`, and there are size/count limits. This is rich behavioral disclosure that goes well beyond the structured safety hints.

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

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

The description is front-loaded with the core purpose, then flows into operational details (background ingestion, limits, alternatives, approval gate) in a compact, information-dense manner. Every sentence contributes actionable guidance without redundancy or 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 no output schema, the description covers everything an agent needs: ingestion behavior, return value (runId), follow-up tools, limits, approval flow, and duplicate-avoidance. Annotations cover safety, and the description fills all remaining gaps, making the definition self-sufficient.

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 kbId, sources, encoding, mimeType, and workspace/approvalId. The description restates the encoding and mimeType rules (utf8 for text, base64 for PDF/docx) and limits (50 sources, ~10 MB each), which are already in the schema constraints. It adds little new semantic meaning beyond what the schema provides, 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 ('Adds documents') and resource ('knowledge base'), and immediately clarifies that ingestion starts. It names sibling tools (workbench_kb_ingestion_status, workbench_kb_search, workbench_kb_documents_list) so an agent can distinguish this tool from alternatives without opening schemas.

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

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

Explicitly tells the agent to check workbench_kb_documents_list first to avoid duplicates, to use workbench_kb_ingestion_status only when the user asks (not poll), and that search works only after ingestion finishes. It also identifies ideal source material (<attached-file> blocks) and notes the approval gate, giving clear 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 the write/non-destructive/openWorld profile, so the bar is lower, and the description adds genuinely new behavior: the tool may return a `needs_confirmation` envelope, which explains the approvalId parameter path. It does not state permission requirements, name-collision behavior, or default visibility (left 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?

Three sentences, front-loaded with the core action, then recipe selection, then the follow-up pipeline. Every clause carries unique information; the trailing note about needs_confirmation is terse but operationally relevant rather than 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 six parameters, no output schema, and only weak annotations, the description covers creation semantics, variant choice, follow-up steps, and the deferred-confirmation path. It omits what the call returns (e.g. the new KB identifier) and any naming/permission constraints, which an agent would still need to guess.

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 83%, so baseline is 3, and the description earns above that by explaining what each recipe produces ('tabular' data queried with SQL, 'graph' entity/relationship extraction) and by tying the confirmation envelope to the approvalId flow. name, workspace, and description parameters gain no further meaning from the description.

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 ('Creates an empty knowledge base') and immediately differentiates the three variants of that resource via recipe semantics. An agent can distinguish this from workbench_kb_add_documents, workbench_kb_get, or workbench_kb_search 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 concrete downstream pipeline guidance: add content with workbench_kb_add_documents, then attach to an agent flow with workbench_flows_attach_knowledge_base before publishing. It does not say when *not* to use this tool (e.g. if a KB already exists, or workspace constraints), so it stops short of full routing guidance.

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

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

Annotations only say destructiveHint=true; the description goes further by disclosing the downstream consequence (flows that search it will find nothing) and the confirmation loop ('May return needs_confirmation'), which is critical for a destructive 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?

Two tightly written sentences with the destruction scope front-loaded and the confirmation caveat last. The parenthetical about where the user can see dependent agents is slightly clunky but still earns its place.

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

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

For a 3-param destructive tool with no output schema, the description covers blast radius, dependent-flow impact, and the confirmation flow. It never states irreversibility outright or clarifies the workspace-parameter interaction, which are the remaining gaps.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds context for the approvalId round-trip by explaining that a needs_confirmation response can occur, and it reinforces the kbId provenance implicitly. Modest but genuine added value.

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 ('Deletes a knowledge base') and immediately scopes the blast radius ('and everything in it'), which implicitly separates it from workbench_kb_document_delete. It does not name a sibling explicitly, so it stops short of the top mark.

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 precondition before acting: check which agents use the KB and tell the user before proposing deletion. That is real usage guidance, but no alternative tool or when-not-to-use condition 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real value beyond that by disclosing cascade behavior (all chunks removed) and the immediate search-visibility effect, plus the possibility of a needs_confirmation response. It stops short of explaining what the confirmation requires or whether the deletion is recoverable.

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 effect, then the id source, then the replace workflow. No filler; each sentence maps to a distinct decision an agent must make.

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 single-document delete with full schema coverage and annotations, this provides everything needed: scope, source of the id, replacement alternative, and the confirmation possibility. No output schema exists, and the confirmation hint adequately pre-frames a non-standard response.

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 four parameters including kbId, workspace, approvalId, and documentId are documented in the schema itself. The description's only parameter-adjacent note ('get the documentId from workbench_kb_documents_list') duplicates the schema's own wording for documentId, adding no new semantics. Baseline 3 applies 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 precise verb (removes) and resource (one ingested document and all its chunks), with scope narrowed to a single document rather than the whole knowledge base. This cleanly distinguishes it from siblings like workbench_kb_delete and workbench_kb_documents_list without needing to open a schema.

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

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

Explicitly routes the caller: get documentId from workbench_kb_documents_list, and to replace a document, remove it then workbench_kb_add_documents the new version. It also signals the confirmation flow via 'May return needs_confirmation', so both prerequisites and alternatives 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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the field set returned and the edge case that results are empty for a KB with nothing ingested or one still ingesting. It stops short of discussing pagination or ordering.

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

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

Front-loaded with what is returned, then the edge case, then the usage guidance. Three tight sentences with no redundant restatement of the title or annotations.

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

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

With no output schema, the description compensates by naming the returned fields, and the schema fully covers both parameters. The only minor gap is the absence of any note on pagination or result limits for a potentially large document list.

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 kbId and workspace are already fully documented in the schema, including the workspace auth requirement. The description adds no parameter-level detail beyond what the schema provides, 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 (List) and resource (documents in a knowledge base) and even enumerates the returned fields (id, name, type, size, chunk count). This lets an agent distinguish it from workbench_kb_search, workbench_kb_get, and workbench_kb_ingestion_status without opening any schema.

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

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

Explicitly names the workflows it serves: call it before workbench_kb_add_documents to avoid re-adding a document, and to obtain the documentId for workbench_kb_document_delete. It also routes the empty-result edge case to workbench_kb_ingestion_status, so nothing 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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. With no output schema, the description carries the return-shape burden and does enumerate the fields returned, which is genuinely useful beyond the annotations; it stops short of explaining what status/ingestion settings values mean.

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 field inventory, then purpose, then the ID source. No filler; only minor density in the field list.

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 single-fetch tool with annotations covering safety and a schema covering both params, the description fills the remaining gaps: what you get back, when to call it, and where the ID comes from. Nothing essential is missing, though status value semantics are 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% and the workspace parameter is richly documented in the schema itself. The description only adds provenance for kbId ('get it from workbench_kb_list'), which is more usage routing than parameter semantics, so the baseline 3 holds.

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 the exact resource and enumerates the concrete fields returned (name, recipe, status, counts, embedding model, ingestion settings), so the agent knows precisely what this tool yields. It also names the sibling workbench_kb_list as the source of the kbId, clearly distinguishing the single-fetch from the list operation.

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

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

It gives a concrete usage context ('read it to confirm a KB has content before pointing a flow at it') and a prerequisite ('get the kbId from workbench_kb_list'). No explicit when-not guidance, but the intended use case is unmistakable.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-structured context: the exact status values, that chunks-written and failure errors are surfaced, and expected latency. It stops short of describing ordering or how long terminal results persist, but adds real value beyond 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?

Three sentences, front-loaded with what is returned, then when to call it, then the parameter. No filler and 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?

There is no output schema, so the description correctly compensates by naming the returned fields. For a read-only status-check tool with fully documented parameters, nothing an agent needs 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 kbId, runId and workspace are already documented, including the workspace-token caveat. The description only reinforces runId's provenance ('the runId the add-documents call returned'), adding minimal meaning beyond the schema — the baseline 3 holds.

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 ('the state of one ingestion run') and enumerates the exact return values (PENDING / RUNNING / DONE / FAILED, chunks written, error). It explicitly names the sibling that creates the run (workbench_kb_add_documents), so an agent can place it correctly among the workbench_kb_* tools.

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

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

Gives explicit triggers ('when the user asks whether their documents are in yet, or before a search that needs them') plus a clear exclusion ('don't poll in a loop'), with the reason and timing expectation (under a minute). It also tells the agent where the runId comes from.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: visibility scoping ("the caller can see") and, importantly, the exact shape of each returned summary, which matters because there is no 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?

Three tight sentences: scope first, then return shape, then the follow-up action. Every clause earns its place, and the return-field enumeration substitutes for the missing output schema rather than 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?

For a one-parameter read-only list tool with no output schema, the description covers scope, visibility, returned fields, and the natural next call. Combined with full schema coverage and read-only annotations, nothing an agent needs 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?

The single `workspace` parameter has 100% schema description coverage, including the personal-token vs workspace-API-key rules, so the schema already carries the semantics. The description's phrase "in the active workspace" is consistent with that but adds no format or override guidance beyond it — baseline 3 for a well-documented schema.

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

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

The description gives a specific verb and resource ("Lists every knowledge base") plus an explicit scope ("in the active workspace the caller can see"), so an agent immediately knows what it returns. It routes to `workbench_kb_search` for content retrieval, but never contrasts itself with the closest sibling, `workbench_kb_get` (single-KB fetch), so differentiation is only partial.

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 reader infers this is the entry point for discovering KB ids, and the sentence "Use an id with `workbench_kb_search` to retrieve content" gives a useful downstream next step. There is no explicit when-to-use/when-not statement and no mention of prerequisites or empty-workspace behavior.

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

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

Goes well beyond the readOnly/destructive annotations by disclosing the credit cost of semantic mode versus the free keyword mode, and by describing the return payload and scoring semantics (cosine 0-1 vs match count). These are operational traits an agent cannot infer from the schema or 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?

Leads with the core purpose, then mode behavior, then return shape, then the prerequisite for obtaining kbId. Every sentence carries distinct information and the ordering follows how an agent would reason about invoking it.

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

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

With no output schema, the description explicitly covers return values (chunk text, document, score) and their interpretation, and covers the two meaningful invocation choices (mode, kbId source). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying mode to cost ('spends a small amount of workspace credit' vs 'free') and by clarifying the score interpretation per mode. The workspace parameter is left to the schema, keeping it from a 5.

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

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

States a specific verb and resource ('Retrieves the most relevant chunks from one knowledge base'), and further anchors it as 'the core RAG primitive'. It is clearly distinguishable from siblings like workbench_kb_documents_list or workbench_kb_get, which enumerate or fetch rather than rank-retrieve.

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 routing context: 'Get a kbId from workbench_kb_list', and explains the semantic-vs-keyword tradeoff (credit cost vs free substring match) that governs mode choice. It lacks an explicit statement of when NOT to use this in favor of another retrieval tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context the annotations cannot: workspace-scoped catalog contents and the `allowed: false` flag on policy-forbidden model nodes with the instruction to avoid authoring with them. It doesn't cover pagination limits or result shape beyond the summary/detail split, so it sits a notch above the annotation baseline rather than far above it.

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

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

Front-loads the authoritative-source claim, then mode selection, then the conceptual distinction between ports and settings, then the workspace policy caveat and `flowId` behavior. Every clause carries a decision or a constraint; nothing is filler.

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

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

No output schema exists, yet the description covers what comes back (summaries vs full node detail), the `allowed` flag, and the flow-pinned imports shape. Combined with the workspace requirement and the authoring-guide cross-reference, an agent has everything needed to call it correctly in either mode.

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

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

With 100% schema description coverage the baseline is 3, and the description clears it by explaining mode semantics: which parameters produce summaries vs single-node detail (inputs/outputs/settings) and what `flowId` actually injects (pinned imports as `imported-<uuid>` nodes). The `workspace` policy note reinforces rather than repeats the schema text.

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

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

States a specific verb (search / get) plus resource (Workbench node catalog) and its scope: node existence and their actual ports. It positions itself as ground truth and differentiates from siblings by pointing at `workbench_flow_authoring_guide` for authoring semantics.

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

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

Explicitly routes between two modes — keyword/category for summaries vs `slug` for full detail — and states the anti-pattern it replaces ('verify against this instead of recalling'). It also names a sibling tool for adjacent concerns and gives the policy rule ('never author with those; pick an allowed model'), so an agent knows both when to call and what to do with the result.

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 readOnly=false and destructive=false, so safety is partly covered, but the description adds real behavioral context beyond them: the three-example build threshold and the special `needs_confirmation` return path. It does not say what happens to existing answers or how the confirmation round-trip maps to approvalId, which the schema handles.

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 and each carrying information (composition of an answer, the three-example build requirement, the confirmation return). Only the parenthetical is slightly clunky, but nothing is wasted.

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

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

For a mutation tool with no output schema, the description covers the key operational facts: what is added, the build-threshold requirement, and the confirmation return. The main remaining gap is not relating this tool to add_examples, but overall it is sufficient to call the tool correctly.

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

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

Schema description coverage is 80%, so the schema documents most parameters (shimId, workspace, approvalId, description). The description adds marginal meaning by framing `answer` as a label plus optional applicability, but the bare `answer` param itself remains undocumented in the schema. Baseline 3 fits.

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

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

Specific verb and resource: 'Adds one answer' and clarifies the answer is a label plus an optional applicability condition. It does not differentiate itself from the closely related sibling workbench_shim_add_examples, so an agent could confuse the two.

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

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

Usage is implied through workflow context ('the shim needs three examples of it before it builds again'), which tells the agent this is part of a multi-step authoring flow. However, there is no explicit when-to-use versus the sibling add_examples tool, nor prerequisites for the first call.

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

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

Goes well beyond the annotations: it discloses idempotency behavior ("Exact duplicates are skipped"), a non-obvious side effect ("The shim rebuilds on its own afterwards"), the follow-up action ("read it again for the new report"), and a special return state ("May return `needs_confirmation`"). These are exactly the traits an agent cannot infer from readOnlyHint/destructiveHint.

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

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

Front-loaded with the core action, then the guidance, side effect and return note in efficient order. Dense but each sentence carries distinct information; minor room to separate content guidance from lifecycle behavior.

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

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

With no output schema, the description carries the return burden and does so by flagging the auto-rebuild/re-read cycle and the needs_confirmation state. A mutation tool with adequate but not exhaustive coverage; nothing critical to calling 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 80%, so the schema already documents shimId, workspace and approvalId; the description correctly does not repeat those. It adds real meaning for the examples field (varied length/register, not paraphrases of the answer's name), but that is marginal against an already well-covered 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 ("Adds example inputs to one answer") scoped precisely to one answer. It is clearly distinguishable from workbench_shim_add_answer and the get/list/create siblings, though it never explicitly contrasts with add_answer, which is the closest sibling.

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 workflow prerequisite ("Read the shim first so new examples fit alongside the existing ones") and directs where to focus effort ("land where recall is low"). It does not name an alternative tool or state when not to use this one, so it stops short of full when/when-not routing.

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

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

Annotations declare a non-read-only but non-destructive, non-open-world write. The description adds real context beyond that: it may return `needs_confirmation`, implying an approval flow mediated by approvalId. It doesn't explain permissions or what else the response contains, 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?

Two tight sentences, front-loaded with the create action and its inputs, then the follow-up action and the confirmation caveat. No filler or repetition of schema text.

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 create tool with no output schema and good schema coverage, the description covers the required inputs, the next-step workflow, and the possibility of a needs_confirmation return. It is nearly complete; only the shape of a successful return and any permission preconditions are 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 description coverage is 83%, so the schema already documents name, question, answers, workspace, approvalId and inputsComeFrom. The description restates the three required inputs but adds no format or constraint detail beyond the schema, making it baseline-adequate rather than additive.

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 (creates) and resource (shim) plus the three inputs it is built from, which distinguishes it from workbench_shim_add_examples and workbench_shim_add_answer by scope. It does not define what a 'shim' is conceptually, but the resource is unambiguous within the workbench namespace.

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 sequencing rule: create first, then add examples with workbench_shim_add_examples, with a concrete threshold (three or more per answer). No explicit when-not or exclusion versus siblings like workbench_shim_add_answer, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered, yet the description goes well beyond them by enumerating the returned payload — question, input sources, per-answer descriptions and examples, build-readiness gaps, and build metrics like held-out accuracy, per-answer recall, confusion pairs, and compiler notes. With no output schema, this return-format disclosure is genuinely valuable.

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 'One shim in full' followed by an em-dash inventory and then actionable guidance. It is dense and long, but nearly every clause conveys concrete content or instruction rather than filler, so it earns its place despite the length.

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

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

For a read-only retrieval tool with no output schema, the description fully compensates by describing the return payload in detail and even explaining how to act on it (write examples toward low-recall answers). Nothing an agent needs to call 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 coverage is 100%: shimId is documented as coming from workbench_shim_list, and workspace documents the personal-token/workspace-key rules. The description adds no additional parameter semantics, so the baseline 3 is appropriate — the schema 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?

The description states exactly what this tool returns: the full contents of one shim — the question, input provenance, every answer with examples, build readiness, and the latest build report. This is clearly distinguishable from siblings like workbench_shim_list (enumeration), workbench_shim_create, and workbench_shim_add_answer/add_examples, so an agent can route correctly without inspecting schemas.

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

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

It gives concrete usage context: 'Read it before writing examples', match the existing examples' register, and place new examples where recall is low or the compiler flags thin answers. That is strong when-to-use guidance tied to a workflow, but it names no explicit exclusion or alternative tool (e.g. don't call if you only need the id list).

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, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real value beyond that: it discloses the exact return shape and the edge case that held-out accuracy is 'null until something is published', which no annotation conveys. Pagination/volume behavior is not mentioned, keeping 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 tight sentences, each doing distinct work: the return-field list, the definition of 'shim', and the entry-point cue. The most actionable guidance (start here for a shimId) is not buried, and there is 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 no output schema, the description carries the return-value burden and does so by enumerating every returned field plus the null-accuracy edge case. Combined with annotations covering safety and a fully documented single parameter, an agent has everything needed to call and interpret 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?

Only one parameter (workspace) and schema description coverage is 100%, so the schema already documents slug semantics and token/default-workspace behavior. The description adds nothing about the parameter, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb+resource (list every shim) and enumerates exactly what the listing contains: id, name, the question it answers, answer/example counts, and published held-out accuracy. It also defines the domain term 'shim', so the agent knows what it is listing without opening any schema, and it is clearly differentiated from the singular workbench_shim_get.

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 as an entry point ('Start here to get a shimId'), which tells it to call this before the get/add_answer/add_examples siblings. It stops short of naming those siblings or stating when not to use it, so it is clear context rather than a full routing rule.

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

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

Annotations already cover readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is handled structurally. The description adds genuinely new behavior: it refuses when the gate belongs to someone else (authorization rule), an invalid verdict errors and lists the real options (error contract), and it prescribes echoing the verdict and note before the call as the confirmation step.

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

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

Three sentences, front-loaded with the core action, then constraints, then the confirmation convention. Dense but every clause carries information; the parentheticals are informative rather than filler. Slightly packed, which keeps it just under 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?

For a mutation tool with no output schema, it covers the action, the valid-input source, the failure modes (wrong label, wrong assignee), and the required confirmation workflow. An agent has everything needed to invoke it correctly without guessing.

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 meaning beyond the schema: verdict values must be one of the gate's labels, a bad label produces an error enumerating the valid ones, and note is the user's reasoning echoed back. That is useful semantic guidance the schema's terse field descriptions do not supply.

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 ('Records THIS user's verdict on a run that is waiting on them') and scopes it to the gate/run concept. It also distinguishes itself from the sibling workbench_tasks_run_view, which is named as the read-side tool that shows the labels, so an agent can tell the two apart 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 context for when to call: a run in waiting_human state that is waiting on this user, with labels sourced from the gate. It also names workbench_tasks_run_view as the way to discover valid labels and warns that a wrong label errors. No explicit exclusions beyond the assignment refusal, so it stops short of a full when/when-not pair.

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

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

Adds substantial behavior beyond the annotations: nothing persists, failures come back as repair-grade problems rather than partial state, the call takes ~15s, the response exposes computer.sites and whether the Task permits each site, and there is a confirmation path. The 'nothing persists' claim is a conservative but not contradictory pairing with readOnlyHint=false, which is based on the compile being a non-trivial compute rather than a pure read.

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 highest-value facts — what it does and that nothing persists — then the failure mode and latency. Dense but nearly every sentence earns its place; the presentation instruction ('which clauses run flows, which you will handle, who decides') is the one line that could be trimmed.

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

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

With no output schema, the description carries the burden of describing returns and does so at a usable level: a proposed plan, repair-grade problems, and the computer.sites field. The finer shape of the plan object is left unspecified, but an agent knows what comes back and what to do with it.

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

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

Schema coverage is 100%, so taskId, sentence, workspace and approvalId are already documented. The description only adds meaning around the sentence (it must be refined iteratively) and doesn't touch taskId or workspace at all, so it sits at the baseline for well-documented params.

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 — compile a sentence into a PROPOSED Task plan — and makes the non-persisting, proposal-only nature explicit. That distinguishes it from workbench_tasks_create, workbench_tasks_freeze and workbench_tasks_set_sites, all of which it names or implies as separate steps.

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

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

Gives concrete usage rules: refine the sentence with the user rather than guessing when the compiler returns problems, use workbench_tasks_set_sites to resolve disallowed sites, then iterate or freeze. It stops short of stating when to reach for compile versus get/update on an existing task, so not a full when/when-not map.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds genuinely new behavior: the result is a draft (not a live process) and must be compiled afterward. It also discloses a user-facing readability constraint — entities must be named, not id-referenced, because people read the sentence on the Task's page. Minor gap: it does not mention the needs_confirmation/approvalId flow that the create call can hit.

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 one-line purpose, then Task definition, then alternative and content guidance — a sensible order with no filler sentences. It runs slightly long and the closing sentence blends authoring guidance with a next-step instruction, but every sentence carries information an agent would otherwise have to guess.

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 no output schema and thin annotations, the description covers what is produced (a draft), how the input should be composed, how to name entities, and what to do next (compile). Not fully complete: the approval/confirmation path and what the create response contains are left to the schema or 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?

Schema coverage is 100%, so the schema alone sets a baseline of 3. The description goes beyond it by specifying what the `sentence` content should look like: the user's own words, trigger first ('When a claim arrives…'), then steps, branches, and who decides what — plus the rule to reference rooms, sheets, tables, flows and people by name rather than id.

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 and resulting state: 'Creates a DRAFT Task from a name + sentence'. It defines what a Task is (people in the loop, or a mapped process; runs measured) and explicitly contrasts it with a routine, so an agent can separate this from routines_create and the many workbench_tasks_* siblings without opening a schema.

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

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

Gives explicit when-to-use ('once the user's sentence feels settled after you've refined it together') and when-not-to-use plus the named alternative ('when nobody but you acts on it and you'd just do the same thing each time on a schedule, make a routine instead (routines_create)'). It also routes the agent to the next step ('then compile it'), which is the natural follow-on action.

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

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

Goes well beyond the destructiveHint=true annotation by describing exactly what is destroyed versus retained: in-flight runs stopped, a waiting gate closed, schedule trigger halted, past runs kept in history. It also warns that the call may return needs_confirmation, which is real behavioral context an agent needs.

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 effect, then the pre-check guidance and the confirmation note. Dense and largely waste-free, though the parenthetical about the gate is a slight tangent.

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 three-parameter tool with no output schema, the description covers the mutation effects, the pre-call verification step, and the possible confirmation response. An agent has everything needed to 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 taskId, workspace, and approvalId are already fully documented in the schema. The description only indirectly adds meaning by explaining the needs_confirmation/approvalId loop, 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 ('Deletes a task') and immediately clarifies the effect scope: in-flight runs stopped, schedule trigger stops, past runs preserved. This distinguishes it implicitly from pause-like siblings such as workbench_tasks_freeze, though no sibling is named directly.

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 pre-flight condition: check workbench_tasks_get for live runs and disclose them before proposing deletion. It also signals the confirmation flow, but it does not name a non-destructive alternative (e.g. freeze) for when the agent should not delete.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real context beyond them: in-flight runs keep their pinned versions, and the action creates a new Task version with activation. It does not clarify what happens to the superseded prior version, so it stops short of fully characterizing the destructive scope.

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?

Five short sentences, each carrying a distinct rule, with the core action front-loaded and the workflow guardrails after. No filler or restatement of the tool name.

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 no output schema, the description covers the prerequisite (compile), the approval gate, the versioning effect on running executions, and the sensible next step. Nothing needed to invoke it correctly is missing, and annotations carry the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a non-obvious constraint on the plan parameter — it must come verbatim from compile and must never be hand-edited, with recompilation as the remedy. That is meaning beyond the schema's plain 'verbatim' note.

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 — freezing a reviewed plan as the Task's next version and activating it — which is unmistakably distinct from compile, run, or start siblings. An agent can tell exactly what state change this causes 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?