Kovca

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by scoping the payload to metadata and stating that inputs and outputs are never stored — a data-boundary disclosure an agent cannot get from the annotations. It does not cover pagination or not-found behavior, which keeps 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?

One sentence, front-loaded with the verb and resource, with the field list and the privacy constraint packed into a single parenthetical. Nothing is redundant and nothing needs to be re-read.

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

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

With only one required parameter, no output schema, and annotations covering safety, the description carries the right load by enumerating the returned fields, which substitutes for the missing output schema. It falls short only on error behavior for an invalid run_id and on any explicit relation to sibling tools.

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

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

Schema description coverage is 100% and the single parameter run_id is documented in the schema with its format example, so the baseline of 3 applies. The description adds no additional meaning about the identifier beyond what the schema already says.

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 (returns) and resource (a run) plus the exact fields returned: status, steps, evaluations, credits, error. That is concrete enough to distinguish it from list_runs by plurality alone, but it never names the sibling, so the differentiation is left implicit.

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

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

Usage is only implied: take a run_id and fetch that run's detail, in contrast to list_runs. There is no explicit statement of when to prefer this over list_runs or run_workflow, and no note on what happens if the ID is unknown.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful context beyond that: output is conditional on access level ('With Author access it also returns the draft') and on workflow type ('automation state if it's an activated automation'), which an agent cannot infer from structured fields.

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

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

A single front-loaded sentence that leads with what is returned and then enumerates the payload. Dense but every clause carries information; only mild cost is that it reads as a long run-on with two colon lists.

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 return values, and it does so thoroughly, including the access-conditional draft payload. It omits error behavior (e.g., unknown workflow_id) and is silent on how versions are ordered beyond 'latest', which keeps it short of a 5.

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

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

Schema coverage is 100% and already documents both parameters, including the default-to-latest behavior for version. The description restates 'the latest (or the given) version' without adding format or edge-case 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 ('Returns a workflow') and enumerates what comes back: published versions, input/output schemas of the latest or given version, enabled state, automation state. The singular, ID-based nature clearly separates it from list_workflows.

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

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

Usage is implied by the required workflow_id, but the description never says when to reach for this versus list_workflows (to discover IDs) or get_run (for execution data). No explicit when/when-not guidance or exclusions.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real value on top: a 30-day retention window, a newest-first ordering guarantee, and a metadata-only payload contract. It does not describe pagination behaviour beyond the limit cap of 100, which is a minor gap given the safety profile is already declared.

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

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

A single sentence carries scope, ordering, the optional filter, the returned field set, and the metadata boundary, with the parenthetical used efficiently. Nothing is padded and the most decision-relevant facts come first.

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

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

With no output schema, the description usefully enumerates the return fields and the metadata-only boundary, so an agent knows what to expect. It is close to complete for a two-parameter list tool; only pagination behaviour past the limit cap is left 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 100%, so both parameters are already documented, and the description only reinforces that workflow_id is optional (omit to list across workflows). It adds no syntax or formatting detail for workflow_id or limit beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ("Lists recent runs") plus scope (last 30 days, newest first) and an optional workflow filter, and enumerates the fields returned. It implicitly distinguishes itself from get_run by stating "Metadata only", though it never names that sibling explicitly.

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

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

Usage is implied rather than stated: "optionally for one workflow" tells the agent the filter can be omitted to span all workflows, and "Metadata only" hints that detail work belongs elsewhere. There is no explicit when-not guidance and no sibling such as get_run or list_waits is named as the alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value beyond them with the 'newest first' ordering and the explicit scope exclusion ('Never the approval's message or answers'), which tells the agent it cannot retrieve approval content here. It stops short of saying how the 'expires or continues' timestamp should be interpreted or how continued waits drop out of the list.

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

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

A single front-loaded sentence: verb and resource first, then temporal ordering, then the payload fields via a colon list. The field enumeration is long but each item carries information an agent would otherwise have to guess, since there is no output schema.

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

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

For a read-only, single-parameter list tool with no output schema, the description supplies the return-shape information that would otherwise be missing and flags the one important data exclusion. Only minor gaps remain: no mention of result limits/pagination in practice or what happens when there are zero open waits.

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 its schema description is already 100% covered, including the default of 20 and the 1-100 bounds. The description of the tool adds nothing about limit or pagination behavior, so the baseline of 3 applies.

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

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

Specific verb plus resource ('Lists the open waits'), and it defines the otherwise opaque domain term by naming the three underlying step types (approval, delay, callback). It also names the exact fields returned, so an agent can distinguish it from list_runs/get_run without opening the schema.

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

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

Usage is implied rather than stated: the field list and the three step kinds make clear this is the tool for finding pending approvals/delays/callbacks, but there is no explicit 'use this when' or 'use get_run instead for X' routing. None of the sibling tools are named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds useful context by stating that each entry carries its latest published version and draft revision. It says nothing about pagination, result limits, or ordering, which matters for a list operation.

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

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

It is a single well-formed sentence with no wasted words, and the resource and returned content are front-loaded. It is lean to the point of omitting any routing or behavioral cues, but nothing present is redundant.

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

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

With no output schema, the description usefully names the returned fields, and annotations cover the read-only nature. However, for a list tool it omits whether results are paginated or filtered by default when query is absent, leaving a real gap 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%, and the single optional query parameter is fully documented in the schema as "Words to search workflow names for." The description adds no further meaning, such as how matching behaves or that omitting query returns everything, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ("Lists the workspace's workflows") and adds the scope of returned data (latest published version and draft revision). It is clear on its own, but it never mentions how it differs from the sibling get_workflow, which retrieves a single workflow.

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

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

There is no guidance on when to use this versus get_workflow or list_runs, and no stated prerequisites or exclusions. An agent must infer that this is the enumeration path from the name and the phrase "the workspace's workflows" alone.

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 openWorldHint=true; the description adds genuinely new context: same billing and rate limits as POST /v1/workflows/{id}/execute, and a concrete list of returned fields. It does not discuss failure behavior or execution duration, which keeps 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?

Three dense sentences with the core action first, then cost/rate-limit parity, then return shape. The field list earns its place because there is no output schema, 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?

For a side-effecting execution tool with no output schema, the definition covers what runs, which version, cost/rate-limit implications, that effects are real, and what comes back. Nothing an agent needs in order to call it 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 coverage is 100%, so baseline is 3. The parenthetical about version defaulting to latest merely restates the schema's own description of 'version', and idempotency_key behavior is documented in the schema rather than 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 (runs a published workflow version) and pins down the default (latest unless version given). The execute-style semantics make it easy to separate from get_run/list_runs, though no sibling is named explicitly.

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

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

Implies usage by noting the workflow must be published and by warning that actions run for real, which is a useful precondition. It never states when to prefer this over inspecting a run (get_run) or listing runs, and offers no exclusions.

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