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

Goes well beyond the annotations: it discloses that nothing is permanently deleted, that an already-deployed version keeps running in the user's Cloudflare account, and that restoration happens in the Nodes2Cloud editor. These are non-obvious consequences an agent must know before invoking a destructiveHint=true 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 tight sentences: effect first, side effects second, invocation condition third. "Archiving twice is harmless" mildly restates idempotentHint but is phrased in user terms and earns its place as a safety reassurance.

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 mutation with full schema coverage, an output schema, and safety annotations, the description supplies the one thing structured fields cannot: the real-world consequence and recovery path. Nothing an agent needs 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 the workflowId description already names list_workflows and create_workflow as sources, so the schema carries the parameter burden. The tool description adds no parameter-level detail, which is the expected baseline here.

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 (archive a workflow) and immediately defines what that means operationally: removed from the active list, non-editable, non-deployable. This clearly separates it from update_workflow, deploy_workflow, and rollback_workflow siblings.

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

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

"Only use this when the user asks to remove a workflow" gives an explicit selection condition, and the restore path tells the agent how the action is undone. It does not name a sibling alternative for harder removal, but none exists in the sibling list, so the guidance is effectively complete.

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, openWorldHint, and non-idempotent, so the safety profile is covered; the description adds genuinely new context by stating it executes for real in the user's Cloudflare account and consumes the connection's daily workflow-call quota. It stops short of describing failure behavior or what specifically a destructive run can affect, which keeps it below 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 sentences, front-loaded with verb, resource, and identifier form, followed by the routing condition and then the cost/discovery notes. No sentence is filler and nothing important is 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?

An output schema exists, so return values need no explanation; the description covers purpose, when to prefer it, quota cost, and where to find valid arguments. It omits error/retry behavior and permission prerequisites for a destructive, open-world call, which is a minor but real gap.

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

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

Schema coverage is 100% and both parameters are documented, including that `arguments` must match the target tool's schema sourced from list_deployed_tools. The description restates that same guidance rather than adding syntax, format, or validation detail beyond the schema, so the baseline of 3 is appropriate.

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

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

Names a specific verb and resource ("Call one of the user's deployed agent-tool workflows ... by its tool name or workflow id") and constrains scope to workflows with an MCP Tool trigger, which cleanly separates it from run_workflow and list_deployed_tools. An agent can identify the right tool 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 an explicit routing rule: use it when the workflow is not in the tool list, with the concrete reason (a workflow deployed since connecting only appears after reconnect but is callable here immediately). It also names the sibling list_deployed_tools as the discovery path for callable tools and their argument schemas.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds meaningful context: the workers.dev step otherwise fails only after a deploy, polling semantics via connectionRequest.complete, and the 'Never returns a secret' guarantee. However, it partly restates response fields that the output schema already documents, so it earns credit for the failure-mode and security notes rather than full behavioral 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?

Two sentences, both dense; the core purpose is front-loaded. The nested parentheticals make the first sentence heavy, 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?

Output schema exists so return values needn't be explained, yet the description still highlights the key field for the polling loop (connectionRequest.complete). Combined with the auth/setup prerequisites it covers everything an agent needs to call it correctly.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so baseline is 3; the description adds real meaning by tying sessionId to polling a request_connections session and workflowId to reporting unconnected node providers (missingProviders).

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

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

States a specific verb+resource (check whether the user can deploy and what is missing) and enumerates the concrete scopes: Cloudflare connection incl. the workers.dev subdomain step, and per-workflow missingProviders. Clearly distinguishable from siblings like get_deployment_status or validate_workflow.

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

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

Gives explicit timing ('Call it early, while building') and a named sequencing rule with its alternative ('After request_connections, call it again with that sessionId'). The when-to-call and what-to-call-after are both stated.

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

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

Annotations already flag destructive=true, idempotent=false and openWorld=true; the description goes beyond them by explaining that terminate leaves completed steps in place and that a mismatched eventType silently does nothing — a non-obvious failure mode worth knowing. It does not cover auth/permission needs or what pause does to in-flight steps, 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?

Front-loads the action list, then conditions, then the failure mode and the alternative — a sensible order with no filler. It is dense but long for a single description; the closing rationale about replay is useful but the densest element.

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

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

For a destructive, non-idempotent control tool, the description supplies the preconditions (get_run for send_event), the semantics of each action, the silent-failure trap, and the correct alternative tool. Return values are covered by the existing output 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 coverage is 80%, so the baseline is 3, and the description adds real meaning: eventType must exactly match an awaitingEvents entry from get_run, and payload is the JSON handed to the waiting node. workflowId/instanceId sourcing (from list_workflows/create_workflow/get_run) is only partly restated, so not a full 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?

Opens with a precise verb+resource ('Act on one in-flight durable run') and enumerates the four supported operations, so the agent immediately knows the scope. The explicit contrast with run_workflow and the absence of step-replay cleanly separates it from the other run tools (get_run, list_runs).

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 per-action conditions ('terminate stops it where it is', 'pause', 'resume') plus an explicit prerequisite for send_event: read get_run first and use one of its awaitingEvents. It also names the alternative for restarting a workflow (run_workflow) and states why replay is not offered.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), and the description adds non-obvious behavior beyond that: the created workflow is undeployed and inert until deploy_workflow, the response carries id and updatedAt, and there are two refusal conditions. That is genuine context an agent cannot get from the annotations.

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

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

Four short sentences, front-loaded with the action and scope, followed by prerequisite, return, and refusal details in that order. Every sentence carries distinct information with no restating of the name or 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?

With an output schema present, the description needn't enumerate return fields, and annotations cover safety; the remaining risk areas for a create tool — node validation and accidental deploy expectations — are both addressed. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description rises above it by explaining that the graph is optional and by pointing at list_node_types/get_node_schemas as the source of valid node `type` and `data` shapes. It does not add edge-routing or position conventions, so it stops short of a 5.

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

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

States a specific verb and resource ('Create a new, undeployed workflow') plus scope ('optionally with an initial graph'), which cleanly separates it from update_workflow, deploy_workflow, and get_workflow. An agent knows exactly what this produces without opening the schema.

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

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

Explicitly names prerequisites and alternative tools: use list_node_types and get_node_schemas before guessing property names, and deploy_workflow is the tool that actually runs things. It also states when the call is refused (plan workflow limit reached, connection restricted to existing workflows), which is a real when-not condition.

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

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

Adds substantial context beyond the annotations: a 90-second owner-approval wait, that protected connections need an extra approval each, that editing during a pending approval cancels the deploy, and the exact `input_required` elicitation contract. This complements destructiveHint/openWorldHint rather than merely restating them.

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 and the mechanism, then sequences prerequisites, approval behavior, and error paths in a logical order. It is dense but nearly every sentence carries operational consequence; only the closing return-value sentence is mildly redundant given the 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?

Covers the full complexity of a destructive, human-gated deploy: prerequisites, approval timing, cancellation risk, elicitation recovery, and outcomes. Nothing an agent needs to invoke it correctly or recover from a blocked call 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 both parameters are already documented. The description adds meaning by explaining that requestState is only supplied on a retry after input_required and must be paired with the same workflowId, which clarifies the two-parameter interaction beyond the field-level 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 and resource ("Deploy a saved workflow to the user's own Cloudflare account, replacing any live version") and clarifies the mechanism ("The server recompiles the saved graph itself; no code you send is ever deployed"). It does not name a sibling it is explicitly not, so the distinction from run_workflow or call_deployed_workflow is left implicit, but the scope 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?

Gives explicit ordering constraints ("Save and validate first, and call check_setup early") that point at specific sibling tools and the condition for using them. It also defines the approval-wait path, the retry-with-requestState path, and the cancellation hazard, so the agent knows both when to call and how to proceed when it stalls.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description adds real context beyond them: results are newest-first, and a null `source` means neither store had data for the window and is not an error. It stops short of describing volume/pagination limits or log-line format, so it is strong but not exhaustive.

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

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

Three sentences, each doing distinct work: what it returns, when to reach for it, and how to interpret a null result. The resource definition is front-loaded before the usage triggers.

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

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

An output schema exists, so return shape need not be spelled out, and the description still covers the one interpretation trap (null source). With annotations handling safety and schema handling parameters, nothing an agent needs to call or interpret 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 the schema itself documents defaults, enum values, and the source fallback ordering, so the description adds little on inputs. Its mention of `source` refers to the response field rather than the parameter's semantics, which slightly muddies the mapping. 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: read raw log lines and uncaught exceptions produced by a deployed workflow, with explicit ordering ('newest first'). It also names the sibling it complements (get_deployment_status), so an agent can separate the two 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?

Gives a direct trigger ('when a run failed without explanation') and an alternative-path trigger ('or get_deployment_status shows errors you need to see'). The escalation relationship to the sibling tool is explicit rather than inferred.

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

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

Annotations already declare readOnly, idempotent, and openWorld, but the description adds substantial behavior: per-section independence, partial failure via `error` plus `warnings`, caveats to read, plan-gating on drift, and what each source captures. It also notes the GitHub mirror lag and manual deletion detection, which go well 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?

Front-loaded with the core question and then organized by section, with the alternative sibling named last. It is dense but nearly every clause carries useful information, though the long compound sentences slightly reduce readability.

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

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

Given the output schema, the description does not need to restate return values, and it covers everything else an agent needs: section semantics, partial-failure behavior, caveats, plan-gating, and the correct alternative for raw logs.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic meaning to the `include` enum by explaining what stats, health, and drift each measure. It does not add details about the `since` parameter beyond what the schema 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?

Frames the tool around two explicit questions ('is this deployed workflow healthy' and 'is it still what we deployed') and names the resource. It distinguishes each section (stats, health, drift) and explicitly separates itself from get_deployment_logs for raw logs.

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 it (health and drift assessment in one call) and names the alternative sibling for raw log lines with the condition that selects it. It also explains that sections can be omitted for speed, giving the agent a clear usage decision.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety is covered; the description's 'Read-only' repeats that rather than adding to it. It does add value with the disclosure that results come back as `options` label/value pairs or, for field pickers, `fields` with types and allowed values — useful behavioral shape even though an output schema exists. The 'fails later on the user's real data' note is genuine context an agent would otherwise lack.

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

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

Three tight sentences, front-loaded with purpose then the when-to-use rationale, with no filler. Minor waste in restating 'Read-only' when the annotations already say so.

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 four-parameter, nested-object tool with a full output schema, the description supplies what the structured fields cannot: why the call matters and what failure it prevents. It leaves credential acquisition to the schema's `credentialId` note and the check_setup pointer, which is acceptable, 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 coverage is 100%, so the baseline would be 3; the description earns an extra point by illustrating the loader families in prose (tabs, bases and typed fields, questions, calendars), which helps the agent pick the right enum value and understand why `params` varies per loader. It does not name the enum members or map them to required params, leaving that to the schema.

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

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

The description gives a concrete verb and resource ('Ask a connected service which values really exist') and then enumerates real instantiations: spreadsheet tabs, Airtable tables and typed fields, Typeform questions, Google calendars. No sibling tool does this — the neighbors are workflow/run/credential management — so an agent can identify it immediately.

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

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

It states the usage condition explicitly ('Use it while configuring a node') and explains the failure mode of not using it ('a guessed tab or field deploys fine and only fails later on the user's real data'), which is a strong motivating rationale. It stops short of naming a competing tool or a when-not-to-use case, and there is no direct alternative to point at.

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

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

Annotations already declare readOnly/idempotent/non-open-world, so safety is covered. The description adds genuinely new behavior: a bad type id returns an `error` entry inside the result rather than failing the whole call, which changes how an agent should handle mistakes and batch types together.

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: what it returns, when to call it, and how failures surface. The payoff statement ("exact rather than guessed") is front-loaded and every clause earns its place.

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

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

An output schema exists, so return shape needn't be spelled out, yet the description still flags the partial-error behavior that an output schema alone would not make obvious. For a single-parameter read tool this covers 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 coverage is 100% and the `types` field already documents the array-of-type-ids contract with an example. The description only restates "one or more node types" and adds no syntax, batching, or limit guidance beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ("Get the full property schema of one or more node types") and enumerates what the schema contains (keys, types, options, defaults, required flags, input/output ports). It implicitly separates itself from list_node_types by returning property-level detail rather than a type catalog, though it never names that sibling 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?

"Use it before writing a node's `data` so property names are exact rather than guessed" gives a concrete trigger condition tied to the downstream task. It lacks an explicit when-not or a named alternative (list_node_types, get_dynamic_options), so the routing is clear but not fully disambiguated.

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

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

Annotations already declare readOnlyHint/idempotentHint, so the description correctly spends its words elsewhere: it discloses that workspace limits are inherited from the owner's plan, a non-obvious inheritance rule an agent could not infer from the schema. It does not mention cost, caching, or freshness of the returned limits.

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

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

Three sentences, front-loaded with the payload contents and ending on the actionable rationale. The middle sentence is long but each clause names a distinct limit dimension, so nothing is padding; it could be tightened slightly.

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

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

An output schema carries the return shape, and the description supplies the conceptual framing the schema cannot: what the limits mean, how workspace vs. user plan interact, and why the caller should check before refusing. Nothing needed to invoke a no-arg read tool 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?

Zero parameters, so baseline is 4; the description correctly avoids inventing parameters and instead explains that limits are resolved per workflow owner rather than passed in.

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

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

Opens with a specific verb+resource ('Read the user's plan and its limits') and enumerates what those limits cover: saved/live workflows, deployed tools offered to agents, and included features. No sibling tool in the list deals with plan/entitlement data, so the boundary 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?

Gives an explicit trigger: consult it before telling a user something is impossible, because refusals are often plan limits. There is no competing alternative tool to route away from, so no exclusions are needed, but it stops short of stating when the call is unnecessary.

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

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

Annotations already declare readOnly/idempotent, so the lower bar applies; the description still adds real behavioral context by disclosing what each mode returns (step status/durations/IO vs state/step history/output/error) and the awaitingEvents field feeding control_run. Lacks any note on size limits or latency for deep step histories, keeping it below 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?

Four dense sentences, each covering a distinct decision point (executionId mode, instanceId mode, mutual exclusion, simple flag), front-loaded with the core purpose. No filler.

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

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

With an output schema present, the description needn't enumerate return shapes, and it still characterizes the content per mode plus the awaitingEvents linkage. Everything an agent needs to choose a mode and call correctly is present.

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%, yet the description adds the crucial non-schema constraint that executionId and instanceId are mutually exclusive one-of, and that simple is only meaningful with instanceId. That is semantics the schema alone does not enforce or convey.

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

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

States a specific verb+resource ('Get one run's details') and immediately splits into the two distinct run flavors (executionId execution logs vs instanceId durable runs), making it distinguishable from list_runs and get_deployment_status. An agent knows exactly what it retrieves.

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 'Pass exactly one of the two' and names where each id comes from (list_runs history / run_workflow or list_runs instances). It also names the downstream consumer (control_run send_event must use awaitingEvents) and when to set simple for cheap polling.

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

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

Annotations already establish readOnly/idempotent/closed-world, so the description focuses on higher-value behavior: versionNumber flips the response from the live draft to a frozen version plus previousVersion (null at version 1), and the updatedAt value is surfaced for a later mutation. That is real added 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?

Two sentences, zero filler, with the primary draft-read purpose front-loaded and the versioning detail following as the conditional case.

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

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

An output schema exists so return values need not be enumerated; the description still flags the key fields (graph, metadata, updatedAt, previousVersion) and covers both call modes. 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: versionNumber's response shape (frozen graph + previousVersion), and the downstream purpose of the returned updatedAt. The workflowId parameter is left to the schema, which is acceptable.

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 ('Get one workflow's editable graph') and enriches it with the payload contents (nodes, edges, settings, metadata), then contrasts the draft read against the versioned read. This clearly separates it from siblings like list_workflow_versions and update_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?

Explicitly names when to pass versionNumber (to inspect a deployed version and its predecessor) and points to list_workflow_versions for numbers, plus explains that the returned updatedAt is an input to update_workflow. No explicit when-not-to-use guidance, but the routing context is concrete.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: results are metadata only and 'no secret or token is ever returned', which is important for an agent reasoning about credential handling. Minor gaps (ordering, empty-state behavior) remain but output schema likely covers return shape.

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, each with a distinct job: what it returns, the security guarantee, how to use the id, and when to use a sibling. The scoping statement is front-loaded with 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?

A zero-param, read-only list tool with an output schema and full annotation coverage needs little more. The description covers purpose, security guarantee, downstream usage, and sibling routing — everything an agent needs to select and 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description adds no parameter concerns and instead clarifies what the caller does with the result, which is the only semantic surface this tool has.

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

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

Specific verb+resource ('List the services the user has connected') with concrete examples (Slack, Google, Stripe) and an enumeration of the returned fields. It is clearly separable from siblings like check_setup or request_connections.

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 downstream action ('Put a connection's id in a node's credential field when building a workflow') and names the alternative with its selecting condition ('To see only what one workflow still needs, use check_setup instead'). 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, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: it only returns MCP-Tool-triggered deployments, and plan limits may truncate results with a count reported in the response — an agent would otherwise misread a short list as complete.

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

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

Three tight sentences, front-loaded with the scope constraint before the usage hint and the truncation caveat. Every sentence carries distinct information; nothing is padding or restatement of the title.

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

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

An output schema exists, so return-value detail is not required, yet the description still summarizes the payload shape (name, description, argument schema). Combined with the plan-limit caveat and the follow-up tool reference, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool applies. No misleading parameter talk is introduced.

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 (list) plus a precisely scoped resource: workflows deployed with an MCP Tool trigger, i.e. callable as tools. It also states what each entry contains (tool name, description, argument schema), which separates it cleanly from the sibling 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?

Explicitly names the intended scenario (find a workflow deployed after you connected) and routes the agent to the correct follow-up sibling, call_deployed_workflow. That is a when-to-use plus an alternative in a single sentence.

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 readOnly, idempotent and closed-world. The description adds genuinely new behavior: results exclude property schemas to keep the payload small, and no account data is required. It stops short of noting pagination or result-size limits, which is the only 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?

Three front-loaded sentences: what it covers, what it returns and what it deliberately omits, then how to filter and chain. Every sentence carries information an agent needs; nothing is repeated from 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 an output schema present, return-field explanation is optional, yet the description still names the key fields and the deliberate omission of property schemas. Combined with the explicit chaining instruction to get_node_schemas, 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 coverage is 100% and the schema already documents the case-insensitive substring match with an example. The description's 'Filter with name' adds the intended usage sequence but no syntax or matching semantics 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 ('Search the catalogue of node types a workflow can use'), enumerates the categories covered, and explicitly distinguishes itself from the sibling get_node_schemas, which returns the property schemas this tool omits.

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 workflow: filter with `name`, then call get_node_schemas for the exact types you will use. It also states 'Needs no account data', which tells the agent this is usable even before auth/setup. The alternative and the condition selecting it 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?

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds real value beyond them by noting results come from the user's own account, that history is empty until a run exists, and that instances surfaces non-terminal states. It omits retention limits and what happens if the cursor is stale, but the added operational context is strong.

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 source semantics, then pagination and the drill-down pointer. Dense but each sentence carries operational information; the executionId/instanceId field mentions edge toward redundancy given the output schema exists.

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

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

For a read-only list tool with a full schema and an output schema, the definition covers default behavior, mode selection, pagination, and the follow-up tool. 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 baseline is 3, and the description still adds meaning: that history can be empty, that instances includes queued/waiting/paused runs, and that status filtering applies to instances. It largely reinforces rather than duplicates the schema's enum and cursor notes.

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

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

States a specific verb and resource ('List a deployed workflow's recent runs') plus the scope ('newest first, read on demand from the user's own Cloudflare account'). It then splits the behavior into two named modes (source: history vs instances), which an agent can distinguish 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?

Explicitly says history is the default, that it is empty until something has actually run, and that instances is the mode that includes queued/waiting/paused runs. It also names the sibling get_run for the drill-down case and explains the cursor loop, leaving little 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 readOnly/idempotent/openWorld, so the bar is lower, yet the description still adds real behavior: an empty list rather than an error for workflows that never stored a file, and that readPath is a download URL template. Pagination via cursor is also disclosed; rate limits or auth needs are not mentioned.

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 resource scope, then return fields, then the empty-list and paging caveats. No filler and 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?

An output schema exists and the description still summarizes the returned fields (key, size, last-modified) plus the readPath template, so an agent has enough to call and interpret results. Minor omission is any note on permission/auth requirements for the storage bucket.

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 explaining the purpose of readPath and the cursor round-trip. It does not elaborate on limit bounds, which the schema already covers.

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 a precisely scoped resource (the files a deployed workflow's runs stored in its own storage bucket in the user's Cloudflare account). That scope cleanly separates it from siblings like list_workflow_versions or list_runs without needing to name them.

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

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

Usage is implied by the scoping ('deployed workflow's runs') and paging guidance says to pass cursor back, but there is no explicit when-to-use/when-not-to-use statement or named alternative for retrieving a single file's contents versus listing.

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 read-only, idempotent, non-open-world behavior, and the description adds meaningful context beyond that: accessible scope, update ordering, returned fields, and the access-restriction behavior that causes other ids to be refused.

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 compact, front-loaded with the listing operation and scope, and each sentence contributes useful selection or usage context. It does mention returned fields despite an output schema, but that is brief and helps an agent understand what it will get.

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

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

For a zero-parameter list tool with annotations and an output schema, the description covers the key missing context: access scope, ordering, returned identifiers, intended usage, and permission-restriction behavior. Nothing essential for correct invocation is missing.

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

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

There are zero parameters, so the baseline is 4. The description correctly does not spend space explaining parameter semantics.

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

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

States a specific verb and resource (list workflows), clarifies access scope (personal and shared via workspace), and gives ordering (most recently updated first). It also distinguishes the tool's role from single-workflow siblings by saying it is the place to find a workflowId.

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 "Start here to find a workflowId," which gives clear usage context. It also adds a restriction caveat, though it does not explicitly name an alternative tool or state when not to use this one.

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

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

Annotations already declare readOnly, idempotent, and closed-world, so the bar is lower. The description still adds genuine context the annotations don't: results are ordered newest first, the live version is flagged, and versions are created on every deploy — useful for interpreting the output.

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

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

Three tight sentences, front-loaded with what the tool returns, then the underlying model, then the follow-up tools. No filler or 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?

With an output schema present, return-value explanation is unnecessary, and annotations cover the safety profile. The description supplies ordering, the live marker, and cross-tool routing, which is everything an agent needs to call and act on 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?

There is a single parameter with 100% schema description coverage, including the source of the id ('from list_workflows or create_workflow'), so the schema carries the load. The description adds nothing beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List one workflow's deployed versions') with scope details: newest-first ordering and a live marker. It is clearly distinguishable from list_workflows, which lists workflows rather than their versions.

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 to get_workflow for reading/comparing a version's graph and to rollback_workflow for restoring an earlier one, and the 'every deploy creates a version' line establishes the context in which this tool applies. It stops short of stating when NOT to call it, but the alternatives 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 only declare the generic flags (readOnlyHint=false, openWorldHint=false, idempotentHint=false, destructiveHint=false). The description adds the operationally critical, non-obvious behavior: the call does not actually establish a connection, the user must complete it out-of-band, secrets must never be requested in chat, and the result must be resolved by polling check_setup. That is real disclosure the annotations cannot carry.

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

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

Front-loaded with the action, then the sourcing rule, the hard constraint, and the follow-up loop — every sentence is operational. The trailing 'Returns sessionId, connectUrl and expiresAt' duplicates what the output schema already declares and is the one sentence that does not fully earn 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?

Given a two-parameter tool with a full output schema and annotations, the description covers the only things an agent could still get wrong: which provider ids to pass, that it cannot complete the connection itself, the anti-pattern of asking for secrets, and how to detect completion. 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 coverage is 100%, so the parameter definitions already carry the basics (provider id array, optional workflowId). The description still adds value by telling the agent where to source the provider ids and the conditional 'cloudflare' case; it says nothing extra about workflowId, which is the only remaining gap.

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

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

States a specific verb and resource ('Create one short link the user opens to connect the services you name, with one button per service') that an agent can immediately distinguish from siblings like check_setup or verify_connection. The mechanism (one link, one button per service) is concrete rather than abstract.

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 where the provider ids come from ('Use the ids from check_setup's missingProviders, plus cloudflare if it is not connected'), states the constraint ('You cannot create a connection yourself'), forbids the wrong alternative ('must never ask the user to paste a secret into the chat'), and prescribes the follow-up loop ('poll check_setup with the returned sessionId ... until connectionRequest.complete is true'). When, when-not, and the alternative are all named.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, yet the description adds real context beyond them: current live state is replaced, deploys may be refused, and for durable workflows the response warns about runs left in flight by the outgoing version. That is exactly the side-effect and failure-mode detail an agent needs before mutating production.

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

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

Front-loads the core action in the first sentence, then adds prerequisites, refusal, warning, and the draft flag in descending importance. Every sentence carries information, though the final restoreDraft clause overlaps with the schema.

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

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

Output schema covers return values, so the description needn't explain them, and it still calls out the notable warning payload for durable workflows. Combined with the refusal condition and argument sourcing, nothing an agent needs to invoke this destructive tool 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 workflowId, versionNumber and restoreDraft are already documented. The description restates the restoreDraft behavior ('also load that version back as the editable draft') without adding format or edge-case detail, so it neither compensates for a gap nor materially extends 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?

Names a specific verb and resource: making an earlier deployed version live again, replacing what is currently running. This clearly separates it from update_workflow (editing) and deploy_workflow (shipping the current draft).

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 the source for the required argument (list_workflow_versions), an explicit gating condition ('Only do this when the user asks'), and a hard refusal case (owner disabled deploys for the connection). An agent knows both when to call it and when it will fail.

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

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

Annotations already mark this destructive and non-idempotent, but the description adds critical behavior: old callers break immediately, the new secret takes a few seconds to propagate, a single 401 should be treated as delay, and the operation is refused if deploys are disabled.

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 sentences, each carrying needed information: action, danger, propagation warning, and refusal condition. The destructive warning is front-loaded after the action statement, 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?

The tool has an output schema, so return values need not be described. For a destructive secret-rotation operation, the description covers the important risks, propagation timing, retry behavior, and refusal condition completely enough 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 workflowId parameter is already documented as coming from list_workflows or create_workflow. The description implies a deployed workflow but adds no further parameter syntax or constraints beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: generating a new webhook secret for a deployed workflow's trigger, redeploying it, and returning the new secret. It clearly distinguishes this mutation from sibling tools like deploy_workflow or update_workflow by naming the exact resource and action.

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

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

It gives explicit when-to-use guidance: only when the user asks or needs the secret to call the webhook themselves. It also states a refusal condition when the owner turned off deploys, and warns against rotating again after a propagation-delay 401.

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 destructive/openWorld/non-idempotent, and the description adds material context beyond them: it runs in the user's real Cloudflare account against real services, Nodes2Cloud stores nothing, and it counts against a per-connection daily call limit. It also discloses that return shape differs between simple and durable workflows, which no annotation covers. No contradiction with destructiveHint=true.

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 and the return-shape fork, then layers side effects and the rate-limit note. Every sentence contributes a distinct fact with 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?

Even though an output schema exists, the description covers the cases an agent actually needs to act on: interchangeable return types, the follow-up call for durable runs, real-world side effects, data retention, and quota. Nothing required to invoke or interpret 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%, so workflowId, via, payload and instanceId are all self-documented; the description only restates that the payload is an optional trigger input. It adds the useful implicit link that instanceId enables polling via get_run, but that behavior is already spelled out in the schema text. 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 ('Run a deployed workflow once, for real') and then splits the outcome by workflow kind: simple workflows return HTTP status/duration/body, durable ones return instanceId and status. That differentiation makes it identifiable against siblings like call_deployed_workflow or test_run_node 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 says to use it 'after deploying to show the user a real result' and to follow durable runs with get_run, so both the entry condition and the follow-up path are clear. It stops short of naming when to prefer call_deployed_workflow or test_run_node instead, which leaves one sibling comparison 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 flag destructiveHint/openWorldHint/idempotentHint but not why; the description supplies the concrete consequence — the node makes its actual third-party call, so a 'send' node really sends. It also discloses the expression pass-through behavior and that the result names affected fields, which no structured field covers.

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?

Side-effect warning is front-loaded before the alternative routing, and every sentence carries distinct information (real call, expression passthrough, when to use run_workflow instead, return value). No padding.

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

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

With no output schema, the description still states it returns the node's raw output, and it covers the two behavioral traits an agent most needs (real side effects, unresolved expressions) plus the correct escalation path to run_workflow.

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 params are described in-schema (node id within saved graph, workflow id from list_workflows/create_workflow). The description adds no format or sourcing detail beyond that, so the baseline 3 applies.

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

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

States a precise verb+resource ('Run one saved node on its own') and immediately scopes it as a real, side-effecting single-node test analogous to the editor button. It is clearly distinguishable from run_workflow, which it names 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?

Gives the exact use case (verify a node's configuration and connection in isolation) and an explicit exclusion with an alternative: for real inter-node data, deploy and use run_workflow. The 'no upstream run' condition is spelled out rather than inferred.

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 (destructiveHint=true, idempotentHint=false) by disclosing the replace-whole semantics, that omitted fields are preserved, the optimistic-concurrency conflict behavior that leaves state unchanged, and that deployment state is untouched. The new `updatedAt` in the response is also 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?

Three dense sentences, each carrying distinct information: replace semantics, concurrency contract, and blast radius. Front-loaded with the highest-risk fact (whole overwrite) before the procedural details.

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 mutation with an output schema, everything an agent needs is present: required inputs, the concurrency protocol, failure handling, and the deployment boundary. Return values are covered by the output schema and only briefly restated.

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 already 100%, but the description adds critical semantics the schema lacks: passing nodes or edges is a full replacement, not a patch, so the complete lists must be sent. It also frames `updatedAt` as a concurrency token rather than a mere timestamp, though it adds nothing about the per-node/per-edge fields.

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

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

States a precise verb and resource ('Replace a workflow's saved draft') and immediately bounds the scope with 'Does not touch what is deployed', which cleanly separates it from deploy_workflow. An agent knows exactly what state this 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?

Gives concrete when-to-use mechanics: it requires the `updatedAt` from a prior get_workflow or create_workflow, and prescribes the recovery path (re-read and retry) when a `conflict` is returned. It stops short of naming siblings explicitly, e.g. whether validate_workflow should be run first or when to prefer rollback_workflow.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, and the description reinforces this with the key non-persistence disclosure: unsaved nodes/edges 'replace the saved ones for this check only.' It also explains what includeCode returns (Worker script plus target, bindings, size), which annotations and schema do not cover.

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 what the tool does, then when to use it, then the two modes and the optional output flag. No filler and every clause carries distinct information.

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

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

An output schema exists, yet the description still tells the agent what kind of result matters (per-node errors; code and metadata when includeCode is set). Combined with the validation-timing guidance, 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%, so the baseline is 3, but the description adds real cross-parameter semantics the schema only hints at: nodes/edges combine with workflowId to shadow saved data for this check only, and includeCode has an intent ('to show the user') beyond the schema's terse note. Slightly short of 5 since individual parameter shapes are left entirely 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?

States a specific verb and resource ('Compile a workflow without deploying it') plus the output ('report every error, each with the node it concerns'). The contrast with deploying makes it immediately distinguishable from deploy_workflow and get_workflow 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 prescribes timing and the alternative it precedes: 'Use it after every edit and before deploy_workflow.' It also names both invocation modes (saved graph by workflowId, or unsaved graph via nodes and edges) so the agent knows which path to take.

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

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

Adds substantial context beyond annotations: the provider call is a read-only identity check, the result is recorded, and the secret is never returned. The readOnlyHint=false (it persists a status) is reconciled by the description calling out the read-only provider call plus the recorded result, and the not_eligible outcome 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?

Four tight sentences, front-loaded with the action and followed by the trigger, the return shape, and the edge-case outcome. Every sentence carries information an agent needs.

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 tool with an output schema, the description covers action, trigger, side effect, return-shape caveat (never the secret), and the not_eligible failure mode. 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?

Only one parameter and schema coverage is 100%, with the schema already pointing to list_connections or check_setup as the id source. The description adds no further parameter detail, 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 and resource: check a saved connection against its provider and record the result. It also clarifies the identity call is read-only, which cleanly separates it from list_connections and check_setup.

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 it when a node fails with what looks like an authentication error, and explains why access might have since been revoked or narrowed. It also names the exclusion cases (providers that can't be checked alone, owner passkey protection) and the resulting not_eligible status.

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