FlowRunner

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

No annotations are provided, so the description carries the entire burden and does: whole-batch rejection on live versions, atomicity (nothing applied or saved on failure), the error naming the failed operation's index and the resend-the-whole-batch recovery, localAlias lifetime and resolution timing, and the distinction between blocking errors and non-blocking issues/suggestions.

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

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

Front-loaded with purpose and the live-flow workflow, then the localAlias rule, then the result shape — a sensible priority order for a dense tool. It is long and several sentences are packed with multiple clauses, but almost nothing is redundant given the no-annotation, no-output-schema situation.

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 17-variant batch mutation with no annotations and no output schema, the description covers preconditions, atomicity, id substitution, error recovery, and every top-level result field. An agent has enough to construct a correct batch and interpret the response without guessing.

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

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

The top-level schema is bare (0% coverage on workspaceId/versionId/operations), but the description compensates heavily: versionId's live-version restriction, operations' ordering semantics, and the localAlias convention across add_block/add_router_case/add_ai_router_decision/add_agent_tool. It also describes the entire result shape ({ id, version, elementCount, status, errorMessage, results, issues, suggestions }) in the absence of an output schema. Only workspaceId and the 100-item cap go unmentioned.

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 first sentence names the verb, the resource (a batch of operations against the flow at versionId), the ordering guarantee, and the save behavior, then explicitly contrasts with the per-block/per-edge alternative. It enumerates all 17 operation variants so an agent knows the tool's full surface 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 when-to-use ("one call for everything you need built, not one per block/edge") and a full prerequisite workflow for live versions: stop_flow, then apply_operations, then start_flow, with the explicit exclusion that pause_flow does not make it editable. It also states a substitution rule — use localAlias only for batch-created ids, real ids for anything pre-existing.

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?

No annotations exist, so the description carries the full burden, and it does disclose the two behaviors that matter most for a canvas mutation: existing blocks move, "including blocks a person placed," and the change is persisted "immediately." It does not say whether the previous layout can be recovered or what permission level is needed, 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?

Two sentences, no filler, with the scope and persistence guarantee front-loaded before the sibling contrast. The parenthetical "(the canvas auto-arrange)" usefully maps the operation to user-facing terminology rather than wasting space.

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 annotations, no output schema, and only two identifier parameters, the description covers the essential contract: what is rearranged, that it is destructive to manual layout, and that it saves. The remaining gap is the response/verification story and permission requirements for a whole-canvas mutation.

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

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

Schema description coverage is 0% for two required parameters, so the schema provides only names and types. The description never mentions workspaceId or versionId, so it adds no meaning about which workspace/version is rearranged or what an invalid ID produces — the compensation burden falls entirely on a description that ignores parameters.

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 ("Rearrange every block's position as a left-to-right tree"), names the resulting layout, and pins down the scope with "every block." It also differentiates itself from apply_operations by contrasting what each one moves, so an agent can pick between them without opening either schema.

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

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

The second sentence explicitly defines the alternative (apply_operations) and its narrower behavior, which gives clear routing guidance between the two layout-related tools. It stops short of stating a when-to-use condition outright (e.g. "use after adding blocks to tidy the canvas") and offers no exclusions or prerequisites.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the return shape ({ id, flowId, version, name }), the side effect that connections and extension catalog are auto-loaded, and how the returned id is consumed later. It omits permissions/auth requirements and failure behavior, which keeps it below 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 and the return payload, then tacks on the two field-level notes. Dense with semicolons but no filler sentences; every clause contributes information.

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

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

For a simple three-parameter creation tool with no output schema, the description supplies the return fields, the id-reuse contract, and side effects. The main remaining hole is the unexplained required workspaceId, which an agent would have to infer.

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

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

Schema coverage is 0%, so the description must compensate. It explains name (3-50 characters) and description (optional text stating what the flow does), which is a real gain over an undocumented schema, but workspaceId — a required parameter — is never explained, leaving one of three parameters opaque.

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 an empty flow in the workspace') and adds the key modifier 'empty', which distinguishes this from cloning or importing a populated flow. No sibling tool creates flows, so explicit sibling differentiation isn't needed, but it also doesn't contrast with apply_operations or get_flow_json.

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 actionable downstream context: 'pass id as versionId to later calls' tells the agent this is a setup step for subsequent operations, and notes that connections and the extension catalog load automatically so no extra setup call is needed. It does not state explicit when-not-to-use conditions.

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

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

With no annotations supplied, the description carries the full burden and does well: it discloses array semantics, per-position error objects ({ type, error }) rather than whole-call failure, the operationId restriction, and the reduced return shape. It omits permission/auth requirements and any cost or rate considerations, which keeps it just 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?

The content is dense and front-loaded, with the primary purpose in the first clause and the caveats following. The telegraphic semicolon-chained style is compact but slightly harder to scan than plain sentences; every clause does carry information, so nothing is wasted.

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

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

For a tool with no annotations and no output schema, the description covers return fields, error modes for batch calls, the alternate operationId response shape, and the cross-tool call ordering. The only material omission is workspaceId meaning and whether returned values are pre-resolution or expression-bearing.

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

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

Schema coverage is 0%, so the description must compensate, and it does for two of three parameters: `type` gets its accepted forms, valid sources, array behaviour and invalid-value handling, and `operationId` gets its single-type constraint and effect on the response. `workspaceId` is never explained, leaving one gap in an otherwise strong compensation.

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

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

The description opens with a specific verb and resource ("Return a block type's fields, params, sampleResult, connectionInfo/connections, serviceConfig and guide") and enumerates the payload, so the agent knows exactly what it gets back. It further distinguishes the tool from neighbours by stating which identifiers are acceptable and explicitly excluding agentTools ids and knowledge bases.

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

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

It gives an explicit precondition ("Call before add_block / configure_block of that type") and routes the agent to the correct source tools (list_block_types, search_extensions, list_extension_methods). It also states when the operationId variant applies and its restriction, 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?

No annotations are supplied, so the description carries the disclosure burden, and it does well: it makes clear the tool only mints a URL rather than connecting the account, names the rejection condition, and points to list_connections for observing the resulting state. It stops short of stating whether the URL expires or must be opened interactively by the user, which matters for a human-in-the-loop OAuth flow.

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

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

Purpose is front-loaded in the first clause, followed by parameter sourcing and then follow-up steps, with no filler sentences. It is dense but every sentence carries usable information; slightly heavier punctuation-based compression would improve scanability.

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, no-annotation, no-output-schema tool, the description covers purpose, error behavior, parameter provenance, and the post-connection workflow. Remaining gaps are URL lifetime/expiry and the required user interaction, which are minor relative to what is already stated.

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 75%, so the schema already documents hostType provenance in detail; the description still adds a source the schema does not mention (get_block_schema connectionInfo) and groups the three identifying parameters, which helps the agent source them consistently. workspaceId receives no mention in either the description or schema, leaving one required parameter semantically thin.

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: it returns an OAuth sign-in URL for a service requiring a connection. It also separates itself from siblings by clarifying that list_connections retrieves the resulting connection and configure_block applies it, so an agent can tell this apart from the connection-management tools without opening schemas.

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

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

Explicitly scopes use to OAuth-based services and states the negative case (rejected for a service that does not use OAuth). It also supplies the full workflow: obtain identifiers from get_block_schema connectionInfo or a search/list row, then list_connections and configure_block after the account is connected.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose useful context beyond the schema: entries can be unavailable and then carry an unavailableReason, and type callFlow means the tool executes a workspace flow with caller-supplied data. It does not state that this is a side-effect-free read, nor anything about permissions or result size 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?

The description is a single front-loaded paragraph with no filler, and the most actionable detail (toolId handoff) appears early. It is dense but every clause conveys information; only the readme pointer feels slightly tacked on at the end.

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?

Because there is no output schema, describing the row shape (toolId, type, name, description, available, unavailableReason) is genuinely necessary and it is done well. For a one-parameter listing tool with no annotations, the remaining gap is mainly the format and source of workspaceId.

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

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

Schema description coverage is 0% for the single workspaceId parameter, so the description must compensate. It implies the listing is scoped to "the workspace" but never clarifies the expected workspaceId format or where to obtain it (e.g., list_workspaces), leaving the agent to infer it.

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

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

"List what can run in the workspace, one row per tool" gives a specific verb (list) and a resource with explicit row granularity, then enumerates the returned fields. It also differentiates itself from get_dynamic_tool_schema and run_dynamic_tool by naming them as the consumers of toolId, so an agent can tell the three apart.

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 a prerequisite (read the readme "Dynamic tools" section first) and describes the downstream flow: take toolId unchanged and pass it to get_dynamic_tool_schema or run_dynamic_tool. That is clear context, but there are no explicit when-not conditions or mention of alternative listing tools such as list_block_types.

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

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

With no annotations, the description carries the full burden; it does disclose that the return is a description plus a per-tool JSON Schema and that fields differ per tool. It does not mention error behavior for invalid toolIds, workspace scoping, or permissions, leaving notable behavioral gaps for a lookup 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 compact clauses, front-loaded with the purpose, then parameter provenance, then the sequencing instruction. Every sentence earns its place.

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

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

For a two-parameter schema-lookup tool with no output schema, the description conveys what comes back and that it varies per tool, which is the critical information. Missing workspaceId meaning and error handling keeps it short of complete.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully explains where toolId comes from, but the required workspaceId is never explained, leaving half the parameters undocumented.

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

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

States a specific verb and resource ('Return a dynamic tool's description and paramsSchema') and immediately differentiates it from siblings by naming get_dynamic_tools as the source of toolId and run_dynamic_tool as the consumer. An agent can route it without opening any schema.

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

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

Explicitly says to call it before run_dynamic_tool and where to get toolId, which gives a clear workflow context. It stops short of stating exclusions or what to do if the tool is unknown, so it is strong but not fully exhaustive.

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

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

With no annotations, the description carries the whole burden and does so: it warns that a RUNNING run is partial, that initialData values are shortened with initialDataTruncated listing cut paths, that block names/types are absent when the configuration is gone, that failure is only populated for TERMINATED runs, and that olderRunsHiddenByPlan replaces the entire result. It also gives the precise semantics of configChangedSinceRun, including the caveat about edits made after stopping that were not restarted.

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 purpose is front-loaded and almost every clause carries real information, but the result is one dense run-on paragraph with stacked parentheses and semicolons that is hard to scan. Since no output schema exists the length is defensible, yet it could be split into field-oriented sentences without losing content.

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

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

There is no output schema and no annotations, so the description must define the return shape and its edge cases — it enumerates every result field (executionId, versionId, configId, status, terminationReason, timestamps, durationMs, initiator, failure, steps, notExecuted) and explains the degradation cases. That is complete enough for an agent to interpret the response 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 0%, so the description must supply meaning: it explains that instanceKey is derived from list_flow_instances and defines both include values (initialData and pendingOn, including '[] when it waits on nothing') plus the lazily-fetched behavior ('each is fetched only when listed'). workspaceId is never mentioned, leaving one of three parameters undocumented.

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

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

The first clause, 'Overview of one run', names the resource (a single flow instance/run) and the operation, and immediately distinguishes it from list_flow_instances by stating where instanceKey comes from. It also separates itself from get_flow_instance_block, so an agent can tell the three siblings apart 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?

It routes the agent explicitly: instanceKey comes from list_flow_instances, block input/output requires get_flow_instance_block, and configId with versionId should be passed to get_flow_summary / get_node_details / get_flow_json to see the flow as it was at run time. It never states when *not* to use this tool (e.g. use list_flow_instances for discovery), which keeps it short of a full 5.

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

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

With no annotations supplied, the description carries the full burden and does so thoroughly: data returned as recorded, long values shortened with truncated lists { path, kind, originalSize }, a maxChars response budget, and explicit terminal states (executed: false with ranIterations, tooLarge: true, olderRunsHiddenByPlan: true). Permission/visibility behavior is at least flagged rather than hidden.

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

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

Purpose is front-loaded and followed by calling modes, then result shape, then edge cases, so the ordering is sensible and nearly every clause carries unique information. The prose is dense and semicolon-chained, making it slower to scan than it needs to be, but there is little true 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 complex 8-parameter read tool with no annotations and no output schema, the description covers return fields (success, error, input, output, retryAttempts and its subfields), the per-mode extra fields (nodeId, iteration, startedAt, durationMs), truncation behavior, and degrade states. An agent has enough to invoke it correctly on the first try.

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

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

Schema description coverage is 0%, so the description must supply all meaning, and it does for blockExecutionKey, instanceKey, nodeId, iteration (default 0, position inside the innermost loop), match, path (syntax plus concrete examples like output.items.[3].body), and maxChars (range 2000..60000, default 30000). The required workspaceId is never explained, which is the only real gap against 8 parameters.

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: 'Input, output and error of one execution of a block in a run.' It also distinguishes itself from siblings by naming the two upstream sources of its keys (get_flow_instance for blockExecutionKey, list_flow_instances for instanceKey), so an agent can place it in the tool graph without opening a schema.

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

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

Gives explicit calling guidance: two mutually exclusive ways to call, 'Do not mix the two ways,' and a defined follow-up path when nested loops produce multiple matches ('repeat the call with match or a blockExecutionKey'). It does not contrast itself with adjacent diagnostic tools like get_flow_instance_logs, which is the only missing routing guidance.

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

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

With no annotations supplied, the description carries the full burden and discharges it: it discloses default and maximum page size, that paging runs newest-first while each page is returned oldest-to-newest, that text over 1000 characters is truncated, that an unknown instanceKey yields an empty list rather than an error, and that olderRunsHiddenByPlan replaces the whole result. These are exactly the non-obvious behaviors an agent needs before calling.

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 most load-bearing facts (what it returns, where instanceKey comes from) are front-loaded, and the pagination, filter, and result-shape details follow in a logical order. It is dense to the point of being a single wall of clauses, but no sentence 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?

There is no output schema, yet the description spells out the return shape including field names, timestamp format, hasMore, and nextOffset, plus the special olderRunsHiddenByPlan case. For a ten-parameter, unpaginated-looking read tool this is complete enough to call correctly on the first attempt.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: offset is defined as skipping N newest messages, limit gets default 100 and max 1000, nodeId is constrained to one block, textFilter is 'text contains', and period's four values are enumerated with from/to as the mutually exclusive alternative. Only workspaceId is left unexplained, which is a minor gap against ten parameters.

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

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

The opening clause states a specific verb and resource ('Log messages one run wrote') and immediately scopes it to a single run, which distinguishes it from run-listing siblings like list_flow_instances and from block-level siblings like get_flow_instance_block. It also names the tool that produces the required instanceKey, so the resource identity 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?

It tells the agent where to obtain instanceKey (list_flow_instances) and how to choose between the two time-filter modes ('period ... or a custom range from/to; not both'), which is explicit exclusion guidance. What is missing is a direct statement of when to prefer this tool over get_flow_instance or get_flow_instance_block when debugging a failed run.

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

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

With no annotations, the description carries the burden and discloses important behavior: the result is read-only, tied to the run start state, and a configuration snapshot rather than an exact reconstruction. It does not cover permissions, error behavior, or output size.

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 key purpose and timing warning are front-loaded, and the parameter caveat is compact. The sentence is dense but nearly all content is relevant, with only slight awkwardness in phrasing such as 'for the flow.'

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 description gives a useful high-level account of the return value and snapshot semantics, which matters because no output schema exists. However, for a four-parameter tool with no schema descriptions or annotations, it leaves important parameter meaning and invocation details incomplete.

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

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

Schema description coverage is 0%, so the description must explain all four parameters. It clarifies configId and its relationship to a run's versionId, but leaves workspaceId and name entirely unexplained.

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

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

The description identifies a specific resource and format: the final internal-format flow JSON. It also distinguishes this retrieval from inspecting run progress, though it does not use an explicit verb or name every relevant sibling.

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

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

It gives clear timing guidance: call it once work is done, not to inspect progress. It also points to get_flow_instance as the source for configId and versionId, but does not fully contrast itself with all sibling retrieval tools such as get_flow_summary.

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

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

With no annotations, the description carries the full behavioral burden. It does add real value by disclosing the null case ("null if none was ever set"), which tells the agent how to detect an unscheduled flow. It says nothing about behavior for an unknown versionId/workspaceId, permission requirements, or error handling.

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

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

A single sentence that front-loads the return value and the field source, with the null case stated immediately after. Nothing superfluous.

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

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

For a two-parameter read tool, the description covers the essential unknown — what it returns and what it returns when nothing is set — which matters since there is no output schema. The remaining gap, ID provenance, is minor against the tool's simplicity.

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

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

Schema description coverage is 0%, so both required strings are undocumented in the schema. The description gives no meaning for versionId or workspaceId — not their format, where version IDs come from, or whether workspaceId scopes the lookup — so it fails to compensate for the coverage 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 ("Return the flow version's current schedule") and even names the underlying field, metaInfo.schedule. It does not explicitly name the sibling set_flow_schedule, but the read framing makes the read-vs-write split with that sibling inferable.

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 by the word "Return"; there is no explicit when-to-use or when-not-to-use guidance. An agent can reasonably infer this is the read counterpart to set_flow_schedule, but it has to draw that inference itself.

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

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

With no annotations, the description must carry behavioral disclosure and it does a lot: Placeholder Data values are truncated, issues include per-service missing required config, suggestions never affect running the flow, and the configId mode is a read-only snapshot rather than an exact reconstruction. It never explicitly states the default call is read-only/no side effects, nor does it mention response size or any cost/limit beyond the word 'compact'.

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 return contents, which is the right order, and most clauses carry real information. But the payload list is a single very long run-on sentence, and the configId paragraph packs four separate facts into one dense block, so it is harder to parse than its length justifies.

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

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

There is no output schema or annotation, so the description is the only disclosure of return values — which it covers thoroughly, including truncation and the configId variant. The gaps are on the input side (workspaceId, versionId sourcing) and on scale (how large a 'compact' overview gets), which matter for a 3-parameter tool with zero schema coverage.

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

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

Schema description coverage is 0%, so the description must define all three parameters. It explains configId well (source tool, paired with that run's versionId, and how the behavior changes under it) and implicitly ties versionId to that pairing, but workspaceId is never mentioned and versionId's own meaning outside configId mode is left undefined.

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

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

The description states a concrete resource ('compact overview of the flow') and enumerates exactly what it returns: node id/type/name/status, edges, description, Initial Data fields with descriptions and consumers, Placeholder Data, flow-wide issues, and suggestions. That is far more specific than the bare name. It stops short of naming the sibling it replaces (get_flow_json, get_node_details), so an agent still has to infer the boundary from those tools' own descriptions.

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

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

It gives a clear timing rule ('Call before wiring or finishing, not after every add_block') plus a mode switch: use configId from get_flow_instance together with that run's versionId to read the flow as it was at run start. That is explicit when-to-use and a stated negative case. It does not name a competing tool (e.g. get_flow_json) or explain when to prefer it over get_flow_instance.

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

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

With no annotations, the description does real work: it declares the tool read-only, discloses that configId mode suppresses validation issues, and honestly frames the result as a snapshot of block configuration rather than an exact reconstruction. It does not cover permissions or error behavior, but for a read tool the key behavioral traits are surfaced.

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

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

Front-loaded with the purpose in the first sentence, and both sentences carry information rather than filler. The second sentence is dense and grammatically tangled ("a snapshot of the blocks' configuration"), but no sentence is expendable.

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

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

With no output schema and no annotations, the description steps up by describing the return content (field values, connections, validation issues) and the configId variant's behavior. It remains thin on the interaction between versionId and configId and gives no basis for choosing this over the closely named get_flow_instance_block sibling.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It explains configId well (sourced from get_flow_instance and tied to that run's versionId) and implicitly nodeId, but workspaceId is never mentioned and versionId's role is only hinted at through the configId clause.

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 ("full human-readable detail for one node") and enumerates what is returned: every current field value, its connections, and validation issues. It is clear without opening the schema, though it never names a sibling (e.g., get_flow_instance_block) to sharpen the distinction.

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

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

Usage is only implied: the description explains where configId comes from (get_flow_instance) and that it fetches the block as it was at run start, which effectively signals a historical-inspection mode. There is no explicit statement of when to use this tool instead of get_flow_instance_block or get_block_schema, nor any when-not guidance.

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

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

No annotations are supplied, so the description carries the full burden. It discloses that this is a read of current values and the shape of the return, plus a pointer to serviceConfig.missingRequired for gaps, but says nothing about permissions/auth, whether the call fails or returns empty when config is unset, or how missingRequired is meant to be interpreted.

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

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

Three short sentences with the core purpose front-loaded, but the final clause 'Which required values are missing: serviceConfig.missingRequired.' is a fragment whose referent and intent are ambiguous.

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

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

No output schema exists, and the description does supply the return shape, which is the main thing needed. However, for a four-required-parameter tool with no annotations, the missing error behavior and the vague missingRequired reference leave real gaps.

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

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

Schema coverage is 75%, with hostType documented thoroughly in the schema itself (including the cross-tool copy-from-search_extensions rule). The description adds no parameter meaning at all, and workspaceId has no schema description, so the remaining gap is not compensated.

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: reads the workspace's current config values for an extension service, and even sketches the return shape as { [name]: value }. It is clearly distinguishable from set_service_config by the 'Read' verb, though it never names that sibling.

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

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

Gives an explicit applicability precondition — only valid when get_block_schema serviceConfig is non-null — and points the agent at get_block_schema as the gate. It stops short of naming alternatives such as set_service_config or list_extension_services for discovery, so no exclusions are stated.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the exact return shape ({ id, provider, name }) and a security-relevant guarantee that the secret is never returned, which prevents an agent from attempting to fetch credentials. It is silent on pagination and permission requirements, but 'List' plus the stated scope makes the read-only nature clear.

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

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

Two tight sentences: identity and return shape first, the security guarantee second, the follow-up usage last. No filler, and the most important constraints are front-loaded.

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

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

For a one-parameter read tool with no output schema, the description supplies the return field list and the safety note, which is most of what an agent needs to call it and consume the result. The only real gap is the missing link to the sibling list_ai_providers and to how workspaceId is obtained.

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

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

Schema description coverage is 0% for the single workspaceId parameter, so the description must compensate. The phrase 'in this workspace' implies that workspaceId scopes the result, but it never states the format or where to obtain the id, leaving the parameter only partially explained.

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

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

States a specific verb and resource ('List the AI keys saved in this workspace') and enumerates the returned fields, so an agent knows exactly what it gets back. It does not explicitly differentiate itself from the sibling list_ai_providers, which is the only plausible confusion point.

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

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

The closing instruction 'Pass id to the block's AI API key field' tells the agent what to do with the result, which is genuine next-step guidance. However, there is no statement about when to choose this tool over list_ai_providers or any prerequisite/permission context, so the guidance is implied rather than explicit.

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

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

No annotations exist, so the description carries the burden, and it delivers: id casing convention with concrete examples, the failure mode for bad ids, and the fact that deprecated models are excluded from results. It omits nothing critical for a read-only listing, though auth/rate-limit context is absent.

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

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

Dense but front-loaded: purpose and authority claim come first, then id format, then failure mode, then return shape. Some sentences run long and the trailing "provider: a provider id" clause reads as an appended afterthought rather than integrated guidance.

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

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

No output schema exists, and the description supplies the return shape ({ id, label, features }) plus the id format and deprecation behavior. For a one-optional-parameter lookup 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 0% and the single parameter is undocumented in the schema, so the description must compensate — and it does, explaining that provider filters to only that provider's models. It also defines the expected id format, which the bare string type does not 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 and resource ("List AI providers and their current models") and adds a distinguishing scope claim: it is "the only source of valid aiProvider / aiModel values." That separates it cleanly from sibling catalog tools such as list_block_types and list_condition_operators.

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

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

Explicitly tells the agent when to call it (before setting aiProvider/aiModel in ai-agent, ai-router, condition aiQuestion blocks) and why skipping it is risky ("a wrong id fails at save or run"). It also flags the exception case: configure_block accepts any string, so validation only bites later.

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?

No annotations are supplied, so the description carries the full burden; it discloses the response shape for both result sections ({blockType, name, description} and {toolDefinitionId, name, description}) and the important scoping caveat that non-addable or extension block types are omitted. The only gap is that read-only/non-mutating nature and any size or pagination limits on the catalog are never stated outright.

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 statement and then layered with routing and exclusions; every sentence carries informational weight and none is filler. It is telegraphic to the point of being slightly terse (the braces-notation return shape reads like shorthand), which costs a bit of readability but not accuracy.

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

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

There is no output schema, so the description must describe returns, and it does — naming both result sections and their fields. Combined with the explicit exclusions and downstream routing, an agent has everything needed to call this tool and act on its results.

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 to disambiguate; the baseline applies. The description instead spends its words on what the caller receives, which is the useful information for a parameterless lookup.

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: a catalog of built-in block types organized by category, returned from this server. It also draws the boundary immediately — only block types this server can add and configure are listed, and extension blocks are explicitly out of scope. An agent can distinguish it from get_block_schema, add_block, and search_extensions without opening any schema.

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

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

Gives explicit next-step routing: pass the returned blockType to get_block_schema and add_block, while agentTools entries go straight to add_agent_tool with no get_block_schema step. It also names the alternatives for the excluded case (search_extensions, search_shared_extensions, list_extension_methods), so both when-to-use and when-not-to-use are covered.

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

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

With no annotations provided, the description carries the burden and does disclose that this is a non-mutating listing operation, that filtering is optional, and that its output feeds set_condition_parts. It omits anything about return format, ordering, or whether the list is static, which keeps it out of the top band.

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

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

Two sentences, front-loaded with the action and resource, followed by the filter detail and the follow-up tool. No redundant wording or restatement of the name.

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

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

For a single-optional-parameter list tool with no annotations and no output schema, the description covers purpose, filter values, and the consuming tool, which is enough to invoke it correctly. A note on what an operator value looks like would round it out.

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

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

Schema coverage is 0% and propertyType is a bare string with no enum in the schema, so the description's enumeration of the seven accepted type values is substantive added meaning. It does not explicitly map the filter to the parameter name propertyType, but the correspondence is easy to infer.

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 scoped to a condition block's conditionParts, which no sibling tool covers. An agent can distinguish it from list_block_types or get_block_schema 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?

Makes the filter optional and names the downstream tool (set_condition_parts) where the results belong, giving clear workflow context. It does not state exclusions or when to skip the filter, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden. It implies a read-only listing operation and explains where connections come from, but it omits permissions, pagination/ordering, whether revoked connections are included, and any return-shape details.

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 compact sentences with no wasted wording. The purpose is front-loaded, and the downstream use of _id is added immediately after.

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 simple one-parameter list tool, the description covers what is listed, the workspace scope, and how returned IDs are used. The remaining gaps are modest: no return fields beyond _id, no pagination/order, and no auth context.

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

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

Schema description coverage is 0%, so the description must compensate. 'In this workspace' gives semantic meaning to workspaceId as the scoping parameter, but it does not explain the expected ID format or where to obtain a workspace ID.

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

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

The description states a specific verb and resource ('List the OAuth connections') and scopes it to a workspace. It also distinguishes this from the connection-creation path by naming console creation and get_connection_url links.

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

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

It gives clear usage context: use this to find existing connections and take a connection's _id for a block's connectionId. It does not explicitly say when not to use it or directly frame get_connection_url as the alternative for creating connections.

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

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

With no annotations, the description carries the full burden; it does disclose the isAgentTool default of false and the resulting behavioral split, which is genuinely useful. It omits pagination/result-size behavior, permission needs, and the rejection behavior for mismatched identifiers (that detail lives only in the schema).

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

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

Four short front-loaded clauses, no filler: resource and key first, then filters, then the mode flag, then the next-step pointer. Telegraphic style but 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?

For a 7-parameter, no-annotation, no-output-schema tool it covers the calling path and the key flag well, and points to get_block_schema as the follow-up. It never describes what a returned method entry looks like (id, name, action vs trigger shape) or the role of workspaceId, leaving gaps a caller must discover by trial.

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?

At 43% schema coverage, the description supplies meaning the schema lacks: search and registerAs are identified as filters, and isAgentTool's default and mode-switching semantics are spelled out. workspaceId is left entirely unexplained in both places, which keeps it from a 5.

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

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

States a specific verb and resource ('List the methods (actions and triggers) of one extension service') and pins the identifying triplet hostType/packageId/serviceId. This clearly separates it from the sibling list_extension_services, which lists services rather than methods.

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 downstream routing ('Pass a method id to get_block_schema next') and explains which mode to pick via isAgentTool (add_block vs add_agent_tool). It does not explicitly say when to prefer this over search_extensions, only that its flag behaves 'as in search_extensions'.

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

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

With no annotations, the description carries the full burden and does well: it discloses the returned row fields (hostType/packageId/serviceId, requiresOAuth with tri-state null, actionCount, triggerCount), the default row cap of 30, and the follow-on call pattern. It is silent on pagination/offset behavior and any permission requirements for workspaceId, 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?

Front-loaded with scope and purpose, and every clause carries information. The telegraphic fragment style ('Shared extensions: search_shared_extensions or search_extensions.') is dense but readable and wastes no words.

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

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

With no output schema, the row-field enumeration is the right call and is present. However, a list tool capped by limit usually implies pagination, and nothing says whether more rows can be fetched or how ordering works, leaving a real gap for an agent planning to enumerate services.

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

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

Schema coverage is 0%, so the description must compensate and largely does: search is explained as filtering by name/integrationName, limit as a row cap with a default of 30, and isAgentTool as the switch that also returns knowledge bases. Only workspaceId is left to inference from 'this workspace's own'.

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

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

States a specific verb and resource ('List this workspace's own extension services') plus the row granularity and the entity types covered (custom extensions, MCP servers, knowledge bases under isAgentTool). It explicitly scopes to 'this workspace's own', which separates it from search_shared_extensions/search_extensions named in the same breath.

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

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

It routes shared-extension lookups to search_shared_extensions or search_extensions and tells the agent the natural next step is list_extension_methods with the returned triple. What's missing is any explicit 'do not use this when…' for the sibling list_knowledge_bases, which overlaps when isAgentTool is true.

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

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

With no annotations, the description carries the full behavioral burden and does so well: default page size of 20, hard cap of 50, newest-first ordering, mutually exclusive period vs from/to, the includeSummary status-filter exception, and the meaning of olderRunsHiddenByPlan and nextOffset. The only unstated behaviors are read-only/safety posture (implicit from the name but not declared) and any rate/permission constraints.

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?

Content is front-loaded: purpose, then ID sourcing, then filters, then row shape, then result envelope. It is dense and semicolon-chained rather than cleanly structured, but nearly every clause conveys operational information (defaults, exclusivity, field meanings) rather than restating the name.

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

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

There is no output schema, so the description supplies the return envelope (versionId, runs, summary, olderRunsHiddenByPlan, nextOffset) and per-row field meanings including hasErrors/errorHandled/terminationReason nuances. For a 12-parameter filtered listing tool with zero annotation coverage, nothing an agent needs to call it or interpret results is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it enumerates the period enum values, the from/to ISO range form and its exclusivity with period, limit default and max, offset pagination via nextOffset, and the semantics of includeSummary (per-status counts over the same filters, status filter not applied). Only workspaceId is left unexplained, which is a minor omission against 12 parameters.

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?

"List the runs of one flow version, newest first" gives a specific verb, resource, scope, and ordering in one clause. The description immediately separates this tool from get_flow_instance / get_flow_instance_logs by explaining that run instanceKeys from this listing feed those detail tools.

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

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

It states preconditions (flowId, versionId, liveVersionId come from list_flows), the default behavior without versionId (LIVE version searched), and the case where versionId is mandatory (no LIVE version exists). It also names the downstream sibling tools to call with each instanceKey, so an agent knows the follow-up path without inference.

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

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

With no annotations at all, the description carries the full burden and does a fair amount: it discloses the row granularity, that versionId is the latest saved version and the one to build against, that liveVersionId is non-null only when the live version differs, and that a LIVE version cannot be edited. It leaves out the read-only guarantee, pagination/result-size behavior, and any permissions needed.

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 with the action first, then the row shape, with field caveats in tight parentheticals. Nothing is padding.

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

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

There is no output schema, so the description rightly enumerates the returned columns and their version semantics, which is the most valuable thing it could say. It is not fully complete: no ordering, pagination, or handling of flows without a live version beyond the liveVersionId hint.

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 (workspaceId) and schema description coverage is 0%, so the description would need to compensate. "The workspace's flows" implies the scoping role of workspaceId and nothing else; no format, no guidance on where to obtain an ID.

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

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

"List the workspace's flows, one row per flow" gives a specific verb plus resource, and the enumerated row fields make clear this is a summary listing rather than a full JSON dump (get_flow_json) or an instance listing (list_flow_instances). It stops short of naming any sibling explicitly, so it lands at clear-but-undifferentiated.

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: you list flows for a given workspace, and the parenthetical "build against it" hints the versionId is what to use downstream. There is no statement of when to prefer this over get_flow_json / get_flow_summary, and no prerequisites 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?

With no annotations, the description carries the full behavioral burden. It helpfully discloses that a "STALE" status means re-syncing is needed and results may be outdated, but it does not explicitly state read-only behavior, permission requirements, or whether all knowledge bases are always returned.

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

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

Two short sentences front-load the primary purpose and then add the crucial ID-source and STALE-status context. Each sentence adds useful information without waste.

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

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

For a simple one-parameter list tool with no annotations or output schema, the description covers purpose, ID sourcing, and one important status behavior. However, it leaves gaps around workspaceId sourcing and the shape of returned knowledge-base entries.

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 sole workspaceId parameter has 0% schema description coverage, and the description only implies workspace scoping through "this workspace's." It does not explain where workspaceId comes from, its format, or why it is required.

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: "List this workspace's knowledge bases." It also distinguishes the tool from get_block_schema by explaining that get_block_schema does not list knowledge-base IDs.

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 clear usage context: use this to obtain knowledgeBaseId for knowledge-base-* blocks. It explicitly notes that get_block_schema is not a substitute because it does not list IDs, though it does not state exclusions or other alternatives.

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

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

With no annotations, the description carries the full burden. It does disclose the access-scoping behavior ('this user can access'), which tells the agent results are permission-filtered, but it says nothing about result size, ordering, or empty-set behavior 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?

Two short sentences, no filler, and the resource and scope are front-loaded before the returned shape and the downstream hint. 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?

For a zero-parameter list tool with no annotations and no output schema, the description supplies the essential information: what is listed, the scoping rule, and the shape of each item. Only minor gaps remain (ordering/pagination, empty results), which are unlikely to block a correct call.

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 the baseline is 4. The description nevertheless adds useful semantics by naming the returned id field and telling the agent to feed it onward as 'workspaceId', which is meaning beyond the empty schema.

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

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

States a specific verb and resource ('List the workspaces') plus the scope ('this user can access') and even the returned fields ('{ id, name }'), so an agent knows exactly what it gets. No sibling tool lists workspaces, so it is unambiguously distinguishable from list_flows, list_connections, and the rest.

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

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

The only usage guidance is downstream ('Pass id as workspaceId'), which implies this should be called before tools that need a workspace identifier. There is no explicit statement of when to call it, when not to, or what to do if the list is empty, so usage is only implied.

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

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

With no annotations, the description carries the full burden and does substantial work: nothing is deleted, in-flight runs continue, and a run parked at a mid-flow callback cannot be resumed while paused — a non-obvious side effect. It stops short of stating idempotency (what happens if the flow is already paused), any permission requirements, or the return value.

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

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

Three short sentences, each front-loading the most decision-relevant fact (scope, side effects, cross-tool alternatives). No filler or restatement of the tool name.

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

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

For a lifecycle-mutating tool with no annotations and no output schema, the description covers state semantics, irreversible-vs-reversible behavior, and sibling routing well. The remaining gap is parameter meaning, which matters because two required IDs are entirely undocumented.

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?

Both parameters (versionId, workspaceId) have 0% schema description coverage and the description never mentions them, so an agent gets no signal about which identifier selects the flow to pause or whether versionId refers to a live version. With two undocumented required params, the description should have compensated and does not.

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

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

Names a specific verb (pause) and resource (a LIVE flow) and immediately scopes what pausing means: triggers and schedule stop starting runs. It also distinguishes itself from stop_flow and start_flow by name, so an agent can route correctly without opening any schema.

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

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

Explicitly states the alternative for the adjacent need ('A PAUSED flow is not editable — to edit, use stop_flow') and the inverse operation ('start_flow resumes it'). This is genuine when/when-not routing rather than implied usage.

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?

No annotations are supplied, so the description carries the full disclosure burden. It does useful expectation-setting by listing the topic areas the readme covers, including 'what is not supported', but it never states that the call is a read-only, side-effect-free reference fetch, nor anything about output format, length, or token cost of the returned documentation. Adequate but with clear gaps for a no-annotation 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?

The imperative prerequisite is front-loaded in four words, followed by a single scannable content index. The second sentence is a long comma-list that runs on somewhat, but every item is a distinct documentation topic and none is filler padding.

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

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

For a two-sentence, zero-parameter documentation tool with no output schema, the definition gives an agent everything needed to decide to call it first and what it will learn. The remaining omission is the shape and size of the returned text, which is minor given the simplicity of the tool.

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

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

The tool takes zero parameters and the schema has no properties, so there is no parameter meaning to convey and nothing the description could add. The content list in the description is the only relevant scoping information and it is present.

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 verb+resource is clear in effect: read the reference documentation, and the second sentence enumerates exactly which topics that documentation covers (flows, expressions, blocks, extensions, build workflow, unsupported features). It is distinguishable from every sibling, all of which act on concrete flows/blocks rather than returning documentation. It stops short of a single explicit statement like 'returns the platform reference guide', so the actor/return object is inferred from the name.

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

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

'Read first, before any other tool' is an explicit and unusually strong ordering directive, which is the key usage decision for a docs tool. There is no when-not clause and no alternative named, but for a zero-parameter reference read that is largely unnecessary since no sibling overlaps its function.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that a missing dependsOn value is rejected with the offending param named, and that results are paginated via cursor and filterable via search. It does not explain what happens when the param has no dictionary (the stated precondition) or any rate/limit behavior, leaving some behavior undisclosed.

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

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

Every clause conveys real information, but it is delivered as a single run-on stream of semicolon-joined fragments rather than front-loaded, structured guidance. An agent gets the facts but no scannable separation between purpose, prerequisites, and result handling.

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

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

There is no output schema, and the description does define the return shape (label + value pairs) plus pagination, which is what the agent needs. Against 7 parameters at 29% schema coverage, the main residual gaps are workspaceId and the behavior for params without a dictionary, so it is nearly but not fully complete.

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

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

Schema description coverage is only 29%, so the description must compensate, and it does for connectionId (OAuth-only, sourced from get_node_details tools[] or absent for unadded blocks), dependsOnValues (keyed by param name, sourced from get_node_details fields), search, and cursor. paramName is only implied ('a param whose… entry') and workspaceId is never addressed, keeping it below 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?

The description opens with a specific verb and resource: 'Return the current options (label + value) of a param whose get_block_schema entry has a non-null dictionary.' That precondition (non-null dictionary) also distinguishes it from generic schema-lookup siblings like get_block_schema. It falls short of 5 only because the sentence is so dense that an agent must parse a nested clause before grasping that this is an option-enumeration endpoint.

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 supplies concrete conditional guidance: pass connectionId only for OAuth services, populate dependsOnValues for each param listed in the entry's dependsOn, and use search/cursor for filtering and paging. It also closes the loop by telling the agent where the result goes (configure_block / configure_agent_tool params and labels[paramName]). No explicit 'do not use this when…' exclusion is given, so it stops short of a 5.

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

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

With no annotations present, the description must carry the full behavioral burden. It does disclose the two most important traits — the operation has side effects and the result always includes an executionId — but says nothing about permissions/scopes, reversibility, error behavior, or whether workspaceId is required to scope the call.

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

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

Four short clauses, zero waste, with the mutation warning front-loaded ahead of the parameter-sourcing guidance and the return-value note. Every sentence earns its place.

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

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

For a generic dynamic dispatcher with nested free-form params and no output schema, the description covers the invocation workflow well but leaves the workspaceId parameter and failure/permission behavior undocumented. An agent can call it correctly but not predict what will happen when the call is rejected or what the response contains beyond executionId.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully explains where toolId comes from and that params must conform to paramsSchema, which is meaningful guidance the schema cannot give. However, workspaceId is never mentioned, and neither is the fact that params is an arbitrary free-form object validated at runtime.

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 dynamic tool') and immediately flags that it produces side effects, which distinguishes it from the read-only siblings get_dynamic_tools and get_dynamic_tool_schema. It stops short of explaining how it differs from other mutation siblings such as apply_operations or test_run_block.

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

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

Gives a clear prerequisite chain: obtain toolId from get_dynamic_tools and shape params per the paramsSchema returned by get_dynamic_tool_schema. It does not state any when-not-to-use conditions or when to prefer a direct tool over this generic dispatcher, but the sequencing guidance 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?

With no annotations supplied, the description carries the full burden and does so: it discloses defaults (isAgentTool false, limit 30), bounds (max 100), rejection behavior for partial triples and mismatched hostType combos, and the important caveat that requiresOAuth means a connection is needed, not that one exists, pointing to get_block_schema connections.

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

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

Front-loaded with purpose and result shape, then parameter semantics in a logical order, with essentially no filler. It is dense and clause-heavy, using semicolons and parentheticals where short sentences would read more cleanly.

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

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

For an eight-parameter search tool with no output schema, the description covers selection logic, filtering constraints, defaults, limits, failure modes, and the returned row fields. An agent has everything needed to invoke it correctly and to interpret results.

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

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

Schema coverage is only 38%, so the description must compensate, and it does: it defines the permitted registerAs values per isAgentTool mode, the semantics of isAgentTool, the limit default and ceiling, the meaning of requiresOAuth, and the all-three-or-none rule for the service-identifying triple.

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

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

The description opens with a concrete verb and resource: keyword search over extension methods in this workspace and shared extensions, with a stated query format (1-3 words with examples). It also specifies the row shape (id, registerAs, requiresOAuth, hostType/packageId/serviceId). It doesn't explicitly say how it differs from search_shared_extensions or list_extension_methods, so sibling 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?

It spells out exactly which mode to choose: isAgentTool false for add_block actions/triggers, true for add_agent_tool (and notes triggers are never returned in that mode). It gives the registerAs compatibility matrix, the rule that hostType/packageId/serviceId must be passed together, and what happens when query is omitted.

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?

No annotations are provided, so the description carries the full disclosure burden. It does reveal the return shape at a high level ("returns services"), default and maximum result counts, and the intended chaining to list_extension_methods, but says nothing about ranking/relevance, permissions, or what happens when nothing matches.

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

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

Three dense sentences, front-loaded with the core capability and the disambiguating example, then limits, then the next step. No redundant or filler wording.

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 convey returns; it does so briefly ("returns services") and implies rows carry hostType/packageId/serviceId via the next-step instruction. It is complete enough to drive a correct call and follow-up, with minor gaps around result ordering and empty-result behavior.

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 all four parameters are already documented, including limit bounds and the isAgentTool semantics; the description repeats the default/max limit rather than adding to it. The only genuinely additive note is propagating the same isAgentTool value to the next call.

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 ("Search shared extensions") and clarifies the unusual retrieval mode with a concrete intent→service example ("send notifications to a team chat" → Slack, Telegram, Teams). It does not explicitly contrast itself with the sibling search_extensions or list_extension_services, so the distinction between semantic search and plain listing must be inferred.

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

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

Gives a clear usage context (describe the task in plain words) and an explicit follow-up step: call list_extension_methods with the row's hostType/packageId/serviceId and the same isAgentTool. It does not state when to prefer this over search_extensions, so there is no exclusion guidance.

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

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

No annotations exist, so the description carries the full burden and does substantial work: it discloses the LIVE/PAUSED precondition, per-version scoping, deferred effect until start_flow, partial-update semantics for omitted fields, the 30-second default startDate for a new schedule, and that endDate:null clears expiry. It omits permissions/auth requirements and any failure behavior (e.g. what happens if the version is LIVE), 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?

Front-loaded with purpose before the conditional rules, and nearly every clause carries load-bearing information (defaults, requiredness, partial-update behavior). It is a single dense paragraph that folds four schedule modes and six special-case rules together, so a bulleted breakdown of the schedule variants would improve scanability without adding length.

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

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

For a 12-parameter mutation with no annotations and no output schema, the description covers preconditions, defaults, conditional requirements, and partial-update behavior thoroughly. The remaining gaps are the return shape and error conditions, which are the only things an agent could still get wrong.

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

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

With 12 parameters at 0% schema description coverage, the description compensates well: it defines the schedule enum, the conditional requirement of everySeconds for "custom", weekDays range 1-7 with 1=Sunday mapping, everyDays/everyWeeks defaults, enabled default true, and the two boolean initiation flags including their dependency. Only versionId and workspaceId go unexplained, which are the two most consequential required inputs for correct invocation.

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 the whole flow on a clock") and immediately bounds the scope: for a flow without a trigger, and explicitly NOT a polling trigger's frequency. The parenthetical examples ("every morning at 9", "every weekday") make the resource concrete and separate it from the sibling get_flow_schedule, which reads rather than sets.

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

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

Gives clear preconditions and context: requires a saved flow version that is not LIVE or PAUSED, and the schedule only takes effect at start_flow. It also notes enabled:false is equivalent to what stop-scheduled-runs does. It never names sibling tools as alternatives (get_flow_schedule, start_flow, pause_flow), so routing to the read-vs-write counterpart is left implicit.

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?

No annotations are supplied, so the description carries the full behavioral burden. It discloses the validation rule (unknown names rejected with the valid list) but says nothing about whether the write merges with or replaces existing config values, what permissions are required, or what happens to fields omitted from configValues — critical gaps for a mutation tool.

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

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

Two tight sentences that front-load the action and then the configValues contract, with no filler. The semicolon-chained clauses are dense but readable and every clause carries information about validation or sourcing.

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

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

For a 5-required-parameter mutation tool with a nested free-form object and no output schema, the description covers the hardest part (configValues keys and their source) but omits return behavior, permissions, and the undocumented workspaceId. Without annotations to fill the mutation-safety gap, it is adequate rather than complete.

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

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

Schema coverage is 60% and configValues is the weakest-documented parameter (generic object with additionalProperties: {}); the description compensates by explaining its shape as { [name]: value } and citing get_block_schema serviceConfig.fields as the authoritative source for keys. workspaceId remains undocumented in both places, but the description meaningfully upgrades the riskiest parameter.

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

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

States a specific verb and resource: 'Set this workspace's config values for an extension service', with concrete examples of what a service is (Sandbox/Production environment, cluster zone). It is clearly the write counterpart to the sibling get_service_config, 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?

Gives a concrete precondition workflow — names, types and required fields must come from get_block_schema serviceConfig.fields — and warns that any other name is rejected. It does not state exclusions or point at get_service_config for reading current values, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does so well: it discloses rejection conditions (server status INVALID or a false saved validation), the destructive side effects of switchover (old version stops taking runs, finishes in-flight runs, schedule dropped), and the activation effects of a start. The only gap is auth/permission requirements.

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 primary action, then failure handling, then the switchover caveat—good ordering. The dense parenthetical phrasing ('withSwitchover: true when...') and a single long paragraph cost it a point but every sentence carries information.

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

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

For a mutation tool with no annotations and no output schema, the description covers activation effects, failure modes, and switchover semantics. It does not state what the call returns or how to confirm the new LIVE state, which would round it out.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly explains withSwitchover (when to set it and what it does), but versionId and workspaceId are only inferable from their names with no format, sourcing, or precedence guidance.

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 with precise state semantics: 'Make a saved flow version LIVE: its triggers start and its schedule takes effect. Also resumes a PAUSED version.' An agent can distinguish this from pause_flow/stop_flow without consulting 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 explicit conditions: use when promoting a version to LIVE or resuming a PAUSED one, and use withSwitchover when another version is already LIVE (the call otherwise fails). It also names the recovery path for invalid flows (get_flow_summary, apply_operations, retry), leaving nothing to inference.

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

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

With no annotations, the description carries the full burden and largely succeeds: it discloses that in-flight waiting runs are terminated, that no data is deleted, and that the state transition is reversible via start_flow. It omits error conditions (e.g., calling on a READY version) and any permission requirements.

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 dense sentence whose clauses are ordered by importance: action and precondition first, side effects next, resulting state and reversibility last. No filler or redundant restatement of the name.

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

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

For a two-parameter mutation with no annotations or output schema, the behavioral picture is unusually complete — state transition, side effects, and reversibility are all stated. The one meaningful gap is the undocumented workspaceId/versionId semantics.

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

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

Schema description coverage is 0% and the description says nothing about either parameter. "The version returns to READY" hints that versionId identifies the flow version, but workspaceId's scoping role is never explained, leaving both required IDs undocumented.

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

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

States a specific verb and resource ("Stop a LIVE or PAUSED flow") and immediately defines the operational outcome: no new runs, waiting runs ended, version back to READY. An agent can distinguish this from start_flow and pause_flow from the text alone.

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

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

Gives clear applicable state (LIVE or PAUSED) and a follow-up path ("editable with apply_operations", "start_flow makes it LIVE again"). It stops short of explicitly contrasting with pause_flow, the closest sibling, so an agent must infer when pausing is preferable to stopping.

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

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

With no annotations supplied, the description carries the full burden and does so: real side effects, non-idempotent, runs the server-saved version pinned to versionId, triggers return immediately without polling, and blocks reading upstream results see only previously test-run data. It also discloses the ~24 s polling ceiling, the completed: false fallback state, and that retrying re-runs the block rather than resuming.

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?

Semantically dense and front-loaded with the side-effect warning first, which is the right ordering. It is a long run of semicolon-joined clauses packed into one paragraph, so the rejection list and the polling caveat are harder to scan than they need to be.

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 no-annotation, no-output-schema mutation tool this covers the essentials: side effects, idempotency, eligibility rules, upstream-data dependency, and timeout behavior. It stops short of describing what the return payload contains beyond the completed flag, or what permissions the caller needs.

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

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

Schema coverage is 0% across three required parameters, so the description must compensate. It adds real meaning for versionId (the version saved server-side is what executes) and implicitly for nodeId (the block must be issue-free and of an eligible type), but workspaceId is never mentioned and no ID formats or scoping rules are given.

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?

"Execute one saved block now, with real side effects" gives a specific verb (execute), narrows the resource to a single block, and immediately contrasts with whole-flow siblings like start_flow and run_dynamic_tool. The parenthetical examples (sends the email, writes the row, calls the API) make concrete what 'execute' means.

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: triggers only arm themselves and return without polling, repeat/list-iterator/actions-group/triggers-group are rejected and must be test-run at a child, while condition/router/ai-router do execute. It also states the prerequisite that the node must have no issues and that upstream data is only visible if those blocks were test-run earlier.

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