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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered; the description adds the useful prerequisite that account ownership and service type must match. It does not disclose what happens on a mismatch (error vs. silent no-op), whether an existing assignment is replaced, or whether re-assigning is a no-op, which are the remaining behavioral questions for this mutation.

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

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

Two sentences, zero filler, with the action stated first and the constraints immediately after. The parenthetical pointer to list_accounts is compact and useful rather than 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?

For a two-parameter, non-destructive, idempotent tool with full schema coverage and no output schema, the description covers purpose, prerequisites, and where to get the IDs. The only material gap is outcome semantics — replacement of prior assignments and error behavior on service mismatch.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a cross-parameter constraint not expressed anywhere in the schema: the account_id value must match the service of the component_id. That relational rule is genuine meaning beyond the structured fields.

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

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

The description gives a specific verb and resource ('Assign a connected third-party account ... to a component of a flow') plus the reason for doing so ('so the component can authenticate against its service'). It names list_accounts as the source of accounts and get_flow in the schema, which separates it from discovery tools, though it never distinguishes itself from the close sibling get_flow_accounts.

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 two concrete preconditions for a valid call: the account must belong to the authenticated user and must match the component's service. That is clear usage context, but there is no explicit when-not guidance, no mention of what to do if the component already has an account assigned, and no pointer to an alternative when the precondition fails.

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

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

Annotations only declare destructiveHint=false, so the description carries real weight and delivers it: the copy is created stopped and, by default, with no accounts assigned. It doesn't mention any permission requirements or rate limits, but the key state semantics are disclosed.

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

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

Three short sentences: what it does, what state the result is in, and when to prefer it. No redundancy and the core action leads.

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 missing piece is what the call returns (presumably the new flow's ID) — an agent needing the copy's identifier isn't told. Everything else about behavior and defaults is covered.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by explaining the consequence of connect_accounts ('components have no accounts assigned unless connect_accounts is set'), which is more than the schema's terse 'Carry the original's connected accounts over'.

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 ('Copy a flow') and immediately scopes it with 'including its components and wiring', which distinguishes it from create_flow and update_flow in the sibling list.

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 rule: 'Cloning then editing the copy is the safe way to change a flow that is in use.' This implies the alternative (editing a live flow in place) without naming a sibling tool, so it stops just short of a 5.

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

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

Beyond the single destructiveHint=false annotation, the description discloses important behavior: placeholder component keys are accepted, real UUIDs are minted, references are rewritten, the mapping is returned as componentIds, and validation runs on creation. It does not state what happens if validation fails (for example, whether a partial flow is created) or what permissions are required, so it falls short of full behavioral disclosure.

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

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

The description is compact and front-loaded: creation and validation come first, followed by prerequisites, key-rewriting semantics, and next steps. Every sentence carries information needed to call the tool correctly.

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

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

For a create tool with a nested object schema and no output schema, the description explains ID minting and the componentIds mapping but not the full return shape, such as the created flow ID or how validation errors are surfaced. It is adequate but leaves meaningful gaps around outcomes and failure 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 the baseline is 3, but the description adds non-obvious meaning for the `flow` parameter: keys may be readable placeholders rather than UUIDs and are remapped to real IDs. This materially changes how an agent should construct the input, though other parameters such as `stage` and `custom_fields` are left to the schema.

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

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

The first sentence gives a specific verb and resource ("Create a new Appmixer flow") and adds the validation behavior, which clearly distinguishes it from update_flow, clone_flow, and start_flow. An agent can identify the operation without opening the schema.

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

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

The description explicitly names prerequisites and sequencing: read get_flow_authoring_guide first, use get_components for exact types/ports/fields, fix errors with update_flow, then use start_flow. It also makes clear the flow is created stopped, so the agent knows not to expect execution.

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

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

Annotations only declare destructiveHint=false; the description adds the genuinely useful behavior that this is a non-destructive safeguard and that update_flow is irreversible without it, which is exactly the risk context the annotation does not convey. It does not say whether snapshots are capped, versioned automatically, or returned in the response, but the core safety profile is well covered.

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

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

Two sentences, zero filler, and the imperative action plus motivation are front-loaded before the cautionary clause. 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 low-complexity two-parameter create tool with no output schema, the description supplies purpose, trigger condition, and the consequence of skipping it. The only gap is that it never indicates what the call yields (a version identifier usable with restore_flow_version), which would help an agent chain calls.

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

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

Schema description coverage is 100% (both id and label are documented, including a label example), so the baseline is 3. The description adds no parameter-level guidance of its own, such as recommending a descriptive label for later identification, so it neither compensates nor detracts.

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 — 'Snapshot the current state of a flow' — plus the purpose (restorable later). It also names the sibling it complements (update_flow), so an agent can place it among create_flow/update_flow/list_flow_versions/restore_flow_version without opening schemas.

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

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

Gives an explicit triggering condition: take a snapshot before rewriting a flow you did not build, and explains why (update_flow replaces the descriptor, no undo). It stops short of routing to the counterpart tools — restore_flow_version for reverting and list_flow_versions for enumerating existing snapshots — so the lifecycle guidance is clear but incomplete.

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

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

Annotations supply only destructiveHint=false, so the description carries most of the behavioral burden. It discloses that the store is readable and writable by this user's flows, which is useful scoping context, but says nothing about name uniqueness, creation limits, permissions, or what happens if a store with the same name exists.

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

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

A single front-loaded sentence with no filler. The phrasing 'the flows of this user' is slightly awkward but conveys the ownership scope efficiently.

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 creation tool with no output schema, the definition is minimally adequate. It omits whether a store identifier is returned, whether names must be unique, and any failure conditions an agent would need to handle correctly.

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

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

Schema description coverage is 100% and the single 'name' parameter is documented in the schema. The description adds no constraint or format detail beyond that, so the baseline 3 applies for a one-parameter tool whose schema does the heavy lifting.

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

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

The description gives a specific verb and resource ('Create a data store'), which clearly separates it from siblings like list_stores, get_store_records, and set_store_record. It does not explicitly name those alternatives, but the create-vs-read/write distinction is unambiguous from the verb 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_stores for checking existing stores before creation. The only context is an implied ownership scope ('the flows of this user'), which is not framed as guidance.

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

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

Annotations already declare destructiveHint=true, so the description's "permanently" and "cannot be undone" largely restate the structured signal, though the permanence emphasis adds some weight. It does not cover behavior on a non-existent ID, effect on running flows, or any cascading deletion of versions/variables.

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

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

Two short sentences, front-loaded with the action and the irreversibility warning. Nothing is wasted and nothing important is buried.

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

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

For a one-parameter destructive tool with no output schema, the description is functionally sufficient but thin: it does not say what happens to flow versions, variables, or running instances, nor what an error for an unknown ID looks like. Annotations cover the safety profile, so this is a moderate gap rather than a critical one.

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% for the single id parameter, so the schema already carries the semantics. The description's "by ID" adds no format or constraint detail beyond it, matching the baseline for full schema coverage.

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

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

States a specific verb and resource ("Permanently delete an Appmixer flow") plus the lookup key ("by ID"), which distinguishes it from sibling mutation tools like stop_flow or update_flow. It stops short of explicit sibling differentiation, but the name and wording make the target unambiguous.

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

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

Usage is implied by the destructive wording, but there is no explicit guidance on when to use this instead of stop_flow, or whether a flow must be stopped first. An agent must infer the preconditions.

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

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

Annotations already declare destructiveHint=true, so the description's main addition is confirming irreversibility ("This cannot be undone"), which is genuinely useful reinforcement. It stops short of permissions required, whether deletion of a missing key errors or is a no-op, and whether any cascade occurs.

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

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

Two short sentences with zero waste, front-loading the action and immediately following with the destructive consequence. Nothing could be removed without losing meaning.

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

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

For a simple two-parameter destructive tool with full schema coverage and a destructiveHint annotation, the description covers the essentials: what it deletes and that it is irreversible. Missing only edge-case behavior (nonexistent key, authorization), which is minor at this complexity.

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

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

Schema coverage is 100% and both store_id and key are documented in the schema with minLength constraints, so the schema carries the parameter burden. The description adds no syntax, format, or sourcing hints for either parameter, making the baseline 3 correct.

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?

"Delete one record from a data store" names a specific verb and resource and implies single-record scope, which separates it from get_store_records and set_store_record in the sibling list. It never names those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

There is no when-to-use guidance: nothing says to use set_store_record to modify instead, no preconditions, and no note on what happens if the key does not exist. The only implicit signal is "one record," which hints there is no bulk variant.

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?

The destructiveHint=true annotation already flags this as a destructive operation, so the description's "This cannot be undone" mostly reinforces what the annotation declares rather than adding new information. It does add the behavioral note that the message is discarded without being replayed, but says nothing about permissions, error behavior, or whether the message must be in a particular state.

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, both earning their place: the irreversible effect is front-loaded and the no-replay scope follows immediately. No 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?

For a single-parameter delete with no output schema and a destructiveHint annotation, the description covers the essential action and its irreversibility. Minor gaps remain around error conditions and whether any response value is returned, but nothing critical to correct invocation is missing.

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

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

There is only one parameter and schema description coverage is 100%, with the schema itself documenting message_id as "The ID of the message to discard." The description adds no further parameter detail, which is acceptable given the schema already covers it fully.

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

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

The description gives a specific verb+resource combination ("Discard a parked message") and adds the qualifier "without replaying it," which implicitly separates it from the sibling retry_unprocessed_message. It does not name that sibling explicitly, so the differentiation is clear but indirect.

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

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

The phrase "without replaying it" hints at the choice between discarding versus retrying, which is enough to imply usage. However, it never states when to prefer this over retry_unprocessed_message, nor any preconditions such as the message needing to be in an unprocessed state.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that the lookup executes with the owning component's credentials (an auth requirement), that no `transform` is applied so results are the auxiliary component's raw output, and that pointer strings like "properties/event" mean "send that property's value". The remaining gap is return shape and pagination behavior, which matters somewhat for an open-world read.

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

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

Front-loaded with the core purpose, but the parameter-routing advice and the pointer-string note are packed into long em-dash-chained sentences that require re-reading. Every clause carries information, yet the density costs scannability.

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 6-parameter, nested-object tool with no output schema, the description covers the hard parts: where the type/port arguments originate, credential semantics, and the fact that transforms are not applied so the caller must pick the identifier the target field expects. Only the shape of the returned option list and limit behavior are left implicit.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it says component_type and out_port come from the source URL (often a different, auxiliary component) and that component_id must be the field owner already present in a flow. It does not explain `limit`, `messages`, or `properties` beyond what the schema already states.

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

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

States a precise verb+resource pair ("Resolve a field's dynamic options at runtime") and immediately scopes it to fields whose manifest declares a `source` URL, with concrete examples (Slack channel pickers, spreadsheet lists, generated output variables). No sibling tool does this, and an agent can tell it apart from get_components or trigger_component 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 a clear trigger condition (the manifest declares a `source` URL) plus prerequisites for calling: the owning component must already exist in a flow and, for connected services, have an account assigned. It also explains how to derive two of the arguments from the source URL. It stops short of naming a sibling alternative or stating when not to use this tool.

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

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

With readOnlyHint=true already declaring safety, the description adds real value by disclosing what each mode returns (type, description, port names vs. full manifest with input/required fields and output variables) and why that detail matters. It does not cover auth, rate limits, or error behavior, but those are not critical for a read-only inspection tool.

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

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

Three tight sentences in a logical order: what it does, no-arg behavior, with-arg behavior, then the caution. Nearly every sentence earns its place; only the opening "Inspect components of an Appmixer app" lightly restates the title.

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

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

There is no output schema, so the description carries the burden of describing returns — and it does for both modes, though the summary contents and manifest shape are only sketched rather than exhaustively specified. For a two-parameter read-only tool, an agent has enough to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds meaning beyond the schema: it explains the behavioral difference between supplying `component` and omitting it, gives the exact fully-qualified format with a concrete example, and ties the parameter to the downstream purpose (building config.transform). The `app` parameter is left to the schema, which already documents it and points to list_apps.

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

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

The description gives a specific verb and resource ("Inspect components of an Appmixer app") and immediately splits the tool into two clearly described modes: summary listing without `component`, full manifest with it. This distinguishes it from siblings like get_component_options and list_apps, which do different things.

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 clearly when to call it each way — omit `component` for an overview, supply the full type when you need input fields/output variables to build config.transform. The closing rule "Never guess component types, port names or fields" gives strong positive guidance. It stops short of naming specific alternative tools (get_component_options, list_apps) for adjacent needs, so not a 5.

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

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

readOnlyHint already establishes the safety profile, and the description adds useful context beyond it: the descriptor is the JSON definition of components and their wiring, and it can be large. It does not mention pagination, failure modes, or permissions, but for a read-only lookup those are modest gaps.

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 compact sentence front-loads the core purpose, then uses a parenthetical and a conditional clause to cover the optional behavior. No filler and no repetition of the schema.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does: metadata plus an optional flow descriptor. An agent has enough to call it correctly; only return-shape detail for the metadata portion is unspecified.

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

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

Schema coverage is 100%, so both parameters are already documented. The description amplifies include_descriptor meaningfully by explaining what the descriptor contains and tying it to a use case, but adds nothing for the required id parameter. Baseline 3 with a small lift is appropriate.

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

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

States a specific verb and resource ('Get a single Appmixer flow by ID') plus what is returned (metadata, optionally the descriptor). It implicitly separates itself from list_flows and get_flow_status/logs by being the single-flow fetch, but never names those siblings, so the differentiation is inferred rather than stated.

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

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

Gives an explicit conditional for the optional parameter ('Set include_descriptor=true when you need component IDs') and names the downstream consumer (trigger_component), which is real routing guidance. It omits any when-not to use this tool versus list_flows or get_flow_status, so it stops short of full alternative coverage.

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?

The readOnlyHint annotation already establishes this is a safe read with no side effects, so the description only needs to add context. It contributes the useful detail that accounts may be unassigned ("if any"), but says nothing about what happens for flows with no account-requiring components, ordering, or response shape.

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

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

One sentence, front-loaded with the verb and scope, with zero redundant or filler wording. The parenthetical "(if any)" is compact and adds real semantic value about nullable assignments.

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

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

For a single-parameter read-only getter with full schema coverage and a readOnlyHint annotation, the description covers what it returns at a conceptual level (component-to-account mapping). The only mild gap is the absence of an output schema and any hint about the returned structure or the behavior when no accounts are involved.

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

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

Schema coverage is 100% and the single required parameter `id` is documented as the flow ID, so the schema carries the parameter burden. The description adds no meaning beyond that (e.g., accepted ID format or where to obtain the flow ID), which is the baseline expectation at full coverage.

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

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

The description uses a specific verb ("List") and a precisely scoped resource: the components of a flow that need a connected third-party account, plus the currently assigned account. That distinguishes it implicitly from siblings like list_accounts (accounts themselves) and assign_account (mutation), though no sibling is named.

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

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

There is no explicit statement of when to call this versus get_flow, get_flow_variables, or list_accounts, nor any precondition mentioned. The usage is only inferable from the wording "require a connected third-party account," which suggests an inspection/diagnostic context.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with a pure reference lookup that mutates nothing. It adds value by scoping the guide's contents (wiring, config.transform, modifiers, variables, validation failures) so the agent knows what knowledge it will gain. It does not describe the shape or size of the returned text, which is the only remaining behavioral gap.

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

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

Two sentences, zero waste: the first front-loads what the guide contains, the second front-loads the call-ordering rule. Every clause earns its place by naming a concrete topic area an agent would otherwise have to guess at.

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 reference tool with no output schema, the definition says enough about what will be returned and when to call it. It could have noted that the guide is long or that it should be cached across calls, but nothing essential for correct invocation is missing.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain and the baseline of 4 applies. The description correctly implies a parameterless call with no hidden inputs.

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?

Uses a specific verb and resource ('Get the complete guide to writing Appmixer flow descriptor JSON') and then enumerates the covered topics: structure, wiring, input mapping, error handling, and validation failures. An agent can distinguish this reference tool from siblings like create_flow or validate_flow 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 instructs 'Read this before calling create_flow or update_flow,' naming the exact sibling tools and the ordering condition that selects it. This is a clear when-to-use directive with named alternatives 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?

readOnlyHint=true already establishes this as a safe read, so the description's main added value is naming the Lucene-queryable fields. It says nothing about log ordering, retention window, or what a log record looks like, and gives no hint that results may be truncated — all relevant for a log-retrieval 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?

Two sentences, the operation stated first and the optional filter second. The field list is the only length, and it is load-bearing information rather than filler.

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

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

With no output schema, the description carries the burden of describing returns, and 'execution logs' plus a field list only partially covers that — record shape and ordering are left implicit. For a three-parameter read tool it is roughly adequate, but an agent cannot predict what it will get back.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns an extra point by enumerating concrete Lucene fields ('msg', '@timestamp', 'portType', 'port', 'correlationId', 'senderType', 'senderId', 'inputMessages') that the schema does not mention, making the query parameter materially more usable.

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

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

States a specific verb and resource ('Get execution logs of an Appmixer flow'), which is meaningfully distinct from siblings like get_flow, get_flow_status and get_unprocessed_message. It does not explicitly name those siblings or contrast itself with them, so it stops short of a 5.

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

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

The description implies usage through 'Optionally filter with an Apache Lucene query', telling the agent when the query parameter is worth supplying, but it gives no guidance on when to reach for this tool versus get_flow_status or the unprocessed-message tools, and no 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 readOnlyHint already declaring the read-only nature, the description adds valuable behavioral detail: the tool returns the stage as 'running' or 'stopped', which is important because no output schema is provided. It does not mention error behavior for invalid IDs or missing flows, but for a simple read-only status query this is a meaningful addition beyond the annotation.

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 efficient sentence with no wasted words, front-loading the key action and resource and then immediately clarifying the possible return values.

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 read-only tool with annotations and a complete input schema, the description covers the essential behavior by stating the returned stage values. It lacks edge-case guidance such as what happens if the flow does not exist, which prevents a perfect score, but it is otherwise sufficient.

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

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

Schema coverage is 100% and the single 'id' parameter is fully documented there. The description adds no additional meaning about the ID parameter (e.g., format, source, or required permissions), so it meets the baseline for high schema coverage without exceeding it.

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

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

The description states a specific verb and resource ('Get the current stage of an Appmixer flow') and enumerates the possible values, making the tool's purpose immediately clear. It does not explicitly distinguish itself from sibling tools like get_flow or list_flows, which keeps it just below the top score.

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

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

Usage is implied by the purpose: check whether a flow is running or stopped. However, there is no explicit guidance on when to use this tool versus alternatives such as get_flow (for full details) or start_flow/stop_flow (for lifecycle changes), leaving the agent to infer the correct context.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description still adds real value by disclosing what comes back: per-component variable paths plus their schemas. It does not mention whether results are cached, whether an empty/invalid flow errors, or how large flows affect response size, which keeps it off 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, zero filler, with the core return shape front-loaded and the workflow guidance second. The quotation of the path syntax does real work rather than padding.

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

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

There is no output schema, so the description carries the burden of describing return values, and it does so by naming the path structure and noting schemas are included. Remaining gaps are minor: it doesn't sketch the response envelope (per-component grouping, empty-state behavior) for a tool whose output is the entire product.

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

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

Schema coverage is 100%, so both `id` and `component_id` are already documented and the baseline is 3. The description reinforces the component-scoping concept by framing results as "available to each component," but adds no format, default, or scoping behavior beyond what the schema states.

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

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

States a specific verb and resource (get the output variables of a flow) and goes further by naming the exact returned path format "$.<componentId>.<port>.<field>" with schemas. No sibling tool returns variable paths, so an agent can distinguish it from get_flow, get_flow_status, and get_components from the first sentence 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 an explicit trigger ("after create_flow/update_flow") and names the failure mode to avoid ("instead of guessing paths"), which effectively routes the agent away from inventing transform references. It also ties the tool to a concrete downstream use case in config.transform modifiers.

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?

The readOnlyHint annotation already establishes this is a non-destructive read, so the description is not carrying the safety burden. It adds useful return-content detail (keys, values, timestamps) but says nothing about result-set limits or how the default page size of 20 / max of 100 affects completeness of what is 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 with zero filler, front-loading what is read and following with the practical scenario. Every clause contributes either output shape or usage intent.

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

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

With no output schema, the description usefully covers the shape of returned records, which is valuable. However, for a paginated listing tool with three parameters, omitting any note about paging or truncation leaves a meaningful gap for an agent that needs complete data.

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 33%: store_id is documented in the schema as pointing to list_stores, while limit and offset have only types, bounds, and defaults. The description does not explain pagination or paging behavior at all, so it fails to compensate for the low coverage.

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

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

States a specific verb and resource ('Read records of a data store') and even enumerates the returned fields (keys, values, timestamps). It is clearly distinct from siblings like list_stores and set_store_record, though it does not name those siblings directly.

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

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

Provides concrete when-to-use context: inspecting what a flow has stored, or verifying data a flow is about to read. It stops short of explicit when-not-to-use guidance or naming alternatives such as list_stores for discovering store IDs (that hint lives only in the schema).

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

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

Beyond the simple read-only hint, the description discloses vital behavioral traits including that the endpoint requires no credentials, is publicly accessible, and requires the source flow to be actively running. This rich operational context is extremely helpful.

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 definition is maximally efficient. It moves from the core function to the method of use, then to critical constraints, ensuring that all necessary decision-making context is provided without unnecessary jargon or repetition.

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

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

Given the lack of an output schema, the description is perfectly complete. It not only delivers the URL but also explains exactly how that URL should be used and under what conditions it will work, eliminating practical ambiguity for the AI agent.

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

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

With 100% schema coverage, the parameters are clear. The description adds value by contextually linking the IDs to their roles within the flow hierarchy (trigger component in a flow), which is helpful for conceptual understanding of the inputs.

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 clearly states the purpose: to get the public webhook URL of a specific trigger component. It provides a concrete example (e.g., WebhookTrigger) which further refines the resource and distinguishes it from general component metadata retrieval tasks.

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 provides explicit instructions on usage, detailing that the URL should be used for chaining flows via a POST request. Crucially, it defines the operational requirements, such as the flow needing to be running for the webhook to be functional.

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

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

Annotations declare readOnlyHint=true and the description is consistent with a pure read. With no output schema, the description carries the return-value burden and does so concretely, enumerating `err` subfields (message, code, name, stack) and explaining that `messages` is keyed by inPort. It doesn't say what happens if the message no longer exists (already retried or deleted), which keeps it from a 5.

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

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

One sentence, front-loaded with the action and then the payoff ('they usually explain why it failed'). No filler and nothing to trim.

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

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

For a read-only single-record fetch with no output schema, describing both returned structures is exactly the needed context. The only gap is lifecycle behavior — what an empty or missing message means — which an agent debugging a parked message might reasonably want.

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

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

The single message_id parameter has 100% schema description coverage and already points to list_unprocessed_messages as the ID source. The description adds no format, validation, or lookup guidance beyond that, so the schema does all the parameter work.

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

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

States a specific verb and resource — 'Read one parked message in full' — and even names the payload fields returned. It implicitly distinguishes itself from list_unprocessed_messages by stressing 'one', but 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?

The clause 'together they usually explain why it failed' implies a debugging use case, so when to call it is inferable. However, there is no explicit routing versus siblings like retry_unprocessed_message, delete_unprocessed_message, or list_unprocessed_messages, and no prerequisites stated.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: the list is scoped to the authenticated user and accounts are connected in the Appmixer UI, not via this server. It does not discuss pagination or return ordering, but for a read-only listing the added context is meaningful.

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: the first front-loads the purpose, and the second adds only relevant context about account connection. No redundant 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?

For a simple zero-parameter, read-only list tool with no output schema, the definition gives enough to invoke it correctly and understand the account scope. It could mention what an account record contains or whether listing is paginated, but those are minor gaps.

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

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

There are zero input parameters, so there is nothing for the description to document; schema coverage is effectively complete. Per the 0-param baseline, this is adequate without extra parameter detail.

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

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

States a specific verb ('List') and resource ('third-party accounts') and clarifies the scope is accounts connected by the authenticated Appmixer user. It also distinguishes the operation from account connection, which happens in the UI rather than this server, though it does not explicitly name sibling tools such as get_flow_accounts.

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?

Provides context for why accounts matter ('Components of connected apps need an account') and rules out connecting accounts through this server. However, it does not explicitly say when to call this versus get_flow_accounts/list_apps or mention exclusions, so guidance is implied rather than prescriptive.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results are scoped to 'this Appmixer tenant' and that entries are app/connector identifiers, but it says nothing about result volume, whether the full list is returned or paginated, or ordering. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Two short sentences, front-loaded with the action and scope, followed by the sibling hand-off. No filler or redundant restatement of the title.

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

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

For a one-optional-parameter read-only listing tool with no output schema, the definition covers what is listed, how identifiers look, and where to go next. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single optional 'category' parameter is documented in-schema with examples, so the baseline is 3. The description does not mention the category filter at all, so it adds no meaning beyond the schema.

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

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

Specific verb plus resource: 'List apps (connectors) available on this Appmixer tenant', and it disambiguates the returned identifiers with concrete examples like "appmixer.utils" and "appmixer.slack". An agent can distinguish this listing tool from sibling tools such as get_components or list_flows without opening any schema.

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

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

It gives clear usage context and explicitly points to get_components as the tool for drilling into an app's components, which prevents an agent from using this for component discovery. It stops short of explicit exclusions (e.g. it never says the tool does not return components or accounts), and it never mentions the category filter as a usage scenario.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds value beyond that by disclosing the result ordering, the fact that results are scoped to the authenticated user, and the fields returned (IDs, names, stages, modification times). It leaves the sort direction and pagination semantics unstated, which keeps it short of a 5.

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

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

Three short sentences, each carrying distinct information: what is listed and how it is ordered, what is returned, and how to filter. The purpose is front-loaded with zero filler.

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

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

With no output schema, the description usefully summarises the returned fields, and for a three-parameter read-only list tool that is close to sufficient. Only the ordering direction and the limit/offset interaction are left implicit, which is a minor gap since the schema documents the pagination parameters.

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 three parameters are already documented in structured form; the description only restates that `pattern` filters by name, adding no syntax or matching rules beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('List Appmixer flows') plus a scope ('of the authenticated user') and an ordering rule ('sorted by last modification'), so an agent knows exactly what this returns. It does not explicitly contrast itself with retrieval siblings like get_flow, but the enumerate-vs-fetch distinction is implied by 'List'.

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

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

It gives one concrete usage cue ('Use `pattern` to filter by name') but no when-to-use context, no prerequisites, and no explicit alternative such as dropping list_flows in favour of get_flow when a single flow ID is known. Guidance is implied rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is smaller. It usefully adds that versions are rollback snapshots and returns are ordered newest first, but says nothing about pagination behavior, result size limits, or when an empty list occurs.

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, ordering stated up front, and the second sentence earns its place by defining what a version is. No boilerplate or redundancy.

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

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

For a simple read-only list tool with one required parameter and annotations covering safety, the description is nearly sufficient; defining "version" was the key missing piece and it is present. The remaining gap is that without an output schema the agent has no idea what fields a version record exposes (notably the version ID needed for restore).

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 33% — only `id` is documented; `limit` and `offset` carry just type/default/bounds with no meaning in either schema or description. The description adds no parameter guidance at all, 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 ("List saved versions of a flow") plus ordering ("newest first"), which is more precise than the title alone. It doesn't explicitly contrast with siblings like create_flow_version or restore_flow_version, but the read/list semantics are unmistakable.

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

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

Usage is implied rather than stated: an agent can infer this is the discovery step before restore_flow_version, but the description never says so or names any alternative. No prerequisites (e.g., flow must exist or be published) are given.

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

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

With readOnlyHint=true already declaring this a safe read, the description's contribution is the tenant scoping (results are per-tenant, not global) and the function-array context. It says nothing about result volume, pagination, or whether the list is large, which matters for a catalog-style tool. Adequate but not rich.

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

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

Two short sentences, front-loaded with the core purpose and followed by the actionable guidance. No filler, no restatement of the title, and the examples are chosen to illustrate the `g_*` convention efficiently.

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-optional-param read-only listing tool with no output schema, the description covers what the tool is, who scopes it, and when to call it. What's mildly missing is a hint about the shape of each returned modifier (name, category, description — inferable from the filter params but not stated), which would help the agent decide whether to filter or fetch all.

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

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

Schema description coverage is 100%, so `search` (name or description substring) and `category` (with example values) are already fully documented in the schema. The description adds no parameter meaning of its own — notably it never mentions that the list can be filtered at all, so the agent must read the schema to discover that. Baseline 3 given the schema does all the work.

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

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

States a specific verb (list) and resource (modifier functions on this tenant), then pins it down further with the exact naming convention `g_*` and three concrete examples (g_length, g_jsonPath, g_formatDate). The 'usable in a transform's `functions` array' clause anchors the tool to a concrete usage site, so an agent knows precisely what it would get back.

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?

"Check here instead of assuming a function exists" is an explicit when-to-use instruction that steers the agent away from hallucinating a function name — a genuinely useful piece of guidance. It doesn't name alternatives, but none of the listed siblings serve this purpose, so there is nothing to disambiguate against.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It does add useful domain framing (flows read/write stores through appmixer.utils.storage components and require the ID), but says nothing about the shape of the result, ordering, or whether all stores are returned. Adequate but not rich.

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

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

Two sentences, both earning their place: the first fixes what is listed, the second explains why an agent would call it. The motivation is front-loaded rather than buried, and there is no filler.

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

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

For a zero-parameter read-only list with no output schema, the description covers purpose, motivation, and the downstream dependency on store IDs. The only gap is what the listing actually contains (names, IDs, metadata), which the agent must infer from 'look it up here'.

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

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

The tool takes no parameters, so there is no parameter meaning for the description to supply; the baseline for a zero-parameter tool applies. Nothing in the description misleads about inputs.

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 user's Appmixer data stores') with an explicit scope ('the user's'), which cleanly separates it from create_store, get_store_records, and the flow-oriented siblings. It also names the domain concept the resource belongs to, so an agent knows what a 'store' is before calling.

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 trigger for use: when a flow needs a store's ID via appmixer.utils.storage components, 'look it up here rather than guessing it' explicitly rules out fabrication. It stops short of naming the alternatives (create_store for creating, get_store_records for contents), so it is strong context without full routing.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds real domain context beyond that: messages are retained rather than dropped, the originating flow keeps running, and this is the default error-handling destination. It does not mention ordering or whether results are paginated across the full backlog, which limits it to a 4.

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

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

Three short sentences with the core definition first, the operational context second, and the workflow next-step last. Every sentence contributes distinct information; there is no restatement of the title or filler.

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

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

Adequate for a read-only listing tool with no output schema: the agent knows what population is returned and what to do next. The remaining gap is the shape of a listed message (which fields identify a failure) and default ordering, though get_unprocessed_message plausibly covers detail retrieval.

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 description never mentions filtering by flow, execution, or result window, so it adds no meaning beyond the schema. Coverage is 50%, but the two undocumented parameters (limit/offset) are self-describing pagination fields with defaults and bounds, leaving the documented filter fields to carry the semantics. Baseline 3 applies.

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

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

Uses a specific verb and resource ('List messages that failed processing') and immediately disambiguates the concept by contrasting it with dropping ('parked instead of being dropped'). It also explains the mechanism that populates this list ('Stop execution' / onError: storeUnprocessed), making it clearly distinct from list_flows and get_unprocessed_message.

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 when-to-use ('find out what broke') and routes the agent forward to retry_unprocessed_message after remediation, which is an explicit alternative path. It stops short of stating when not to use this over get_unprocessed_message for inspecting a single item, so it is strong but not exhaustive.

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

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

The readOnlyHint and openWorldHint annotations already establish that this is a safe external read, and the description adds that it targets a trigger on a running flow and returns that component's response. It does not disclose whether invoking a webhook trigger causes the flow to execute, whether authentication is required, or how errors are surfaced, which are important behavioral details for a live-flow trigger.

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 no filler. The action, target resource, and distinguishing constraint are all packed into one compact statement.

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 three parameters, one nested query object, and no output schema, the definition covers the call adequately but leaves the return value vague: it only says the component's response is returned, without indicating its format or how failures appear.

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

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

Schema description coverage is 100%, so flow_id, component_id, and the nested query object are already documented in the schema. The description adds nothing beyond that, such as how query keys map to webhook parameters, so the baseline 3 applies.

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

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

The description names a specific action and resource: it sends a GET request to a trigger component and returns that component's response. It also scopes the use case to webhook triggers that listen on GET, which meaningfully distinguishes it from the sibling trigger_component tool without naming it 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?

The condition for use is clear: webhook triggers that listen on GET. It never explicitly says when not to use it or directs the agent to trigger_component for POST-style triggering, so the alternative is only implied by the GET restriction rather than stated outright.

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

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

Annotations only flag destructiveHint=true; the description goes further by naming exactly what is overwritten ('the flow's current descriptor is replaced by the snapshot') and telling the agent how to hedge against data loss. That is precisely the extra behavioral context annotations cannot convey.

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

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

Two tight sentences, zero filler, with the core action stated first and the destructive consequence plus mitigation immediately after. Every clause carries useful 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 two-parameter mutation tool with no output schema and a destructiveHint annotation, the description covers the essential risk and the recommended safeguard. It does not mention permissions or what the call returns, but those are minor against a simple, well-annotated schema.

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

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

Schema coverage is 100% and the schema already documents both id and version_id, including a cross-reference to list_flow_versions. The description adds only the notion that version_id selects a saved snapshot to roll back to, which is marginal beyond the schema.

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

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

The description states a specific verb and resource — 'Roll a flow back to a saved version' — which is unambiguous and clearly distinct from sibling operations like list_flow_versions, create_flow_version or clone_flow. It stops short of naming those siblings explicitly, so an agent must infer the boundary itself.

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

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

It gives concrete when-to-use context plus a prerequisite-style caution: take a version of the current state first if you may want it back. There is no explicit when-not-to-use statement or direct pointer to create_flow_version by name, but the conditional guidance is actionable.

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

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

Annotations only declare openWorldHint and destructiveHint=false; the description adds genuine behavioral insight by explaining that the replay repeats the original input, so the same failure recurs if the root cause is unfixed. It does not address side effects of re-processing or whether the message is removed from the parked queue afterward, 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 short sentences with zero filler; the action is front-loaded and the caveat follows immediately. Every clause carries information.

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

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

For a single-parameter, annotation-covered, no-output-schema tool, the description supplies enough to call it correctly and to anticipate the main failure mode. Minor gaps: no statement of what a successful replay returns or whether the message leaves the unprocessed list.

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

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

There is only one parameter and schema coverage is 100%, with the schema already stating that message_id identifies the message to replay. The description's mention of "original input" contextually ties to message_id but adds no new syntax, format, or sourcing guidance beyond the schema.

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

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

The description states a specific verb and resource ("Replay a parked message") plus the mechanism ("through its component"), which clearly separates it from sibling reads like get_unprocessed_message, list_unprocessed_messages, and delete_unprocessed_message. It does not explicitly name those alternatives, but the operation is unambiguous.

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

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

The second sentence gives a real precondition for use: fix the underlying flow before replaying, because the same input will be re-sent and will fail again. This is actionable when-to-use context, but no explicit alternative action is named (e.g. when to delete instead of retry).

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

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

Annotations declare openWorldHint=true and destructiveHint=false, so safety is covered; the description adds real value beyond that by disclosing the delivery model (broadcast to all matching running flows of this user, not a single target) and the implicit fact that stopped flows get nothing. It does not say whether delivery is synchronous or fire-and-forget, or what happens when no flow 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?

Two short sentences, action first and consequence second, with no filler or hedging. Every sentence carries information an agent needs.

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

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

For a simple two-parameter, non-destructive send operation with full schema coverage and no output schema, the description covers purpose and delivery scope adequately. Minor gap: no indication of the return value or error behavior for an unknown event name.

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 `event` (the event name used for trigger matching) and `data` (arbitrary payload) are already documented. The description reinforces that the event name is the matching key, but says nothing about the shape or handling of `data`, so it stays at the baseline.

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

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

States a specific verb (send) and resource (a named App Event) and immediately explains the effect: running flows with a matching OnAppEvent trigger receive it. That fan-out semantics distinguishes it from the other flow-mutating siblings like trigger_component without needing to name them.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for notifying event-driven flows, and the 'running flows ... with OnAppEvent trigger' clause implicitly says when delivery happens. But there is no explicit when-to-use/when-not guidance, no mention of trigger_component or test_flow as alternatives, and no note on what to do if no flow is listening.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description is consistent with that (set semantics, overwrite by key). Beyond the annotations it clarifies that overwrite of an existing key is the intended behavior and that the value is stored verbatim, but it says nothing about required permissions, whether a prior value can be recovered, or concurrency behavior.

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

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

Three short sentences, front-loaded with the operation, then the parameter gotcha, then use cases. No filler and nothing repeated from the schema verbatim.

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

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

Covers purpose, the tricky value format, and when to reach for it; annotations cover the safety profile and there is no output schema to explain. The only gap is how to obtain a valid `store_id` (e.g. via list_stores), which the description never mentions.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning: it explains that `value` is persisted exactly as given and must be an object, with a worked example {"value": "text"} for the scalar case. That resolves the non-obvious wrapping rule the schema's `additionalProperties: {}` leaves ambiguous.

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 scope: "Create or overwrite one record of a data store." That distinguishes it implicitly from get_store_records and delete_store_record, but no sibling is named, so an agent must infer the routing rather than being told.

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

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

Gives two concrete usage contexts ("seeding data a flow will read" and "correcting a record a flow wrote"), which is real guidance rather than a vague hint. It stops short of explicit exclusions or of pointing at the read/delete counterparts for other cases.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the meaningful precondition about flow validity/completeness, but says nothing about what a successful call produces (an execution? a run ID?), what happens on an invalid flow, or whether assigned accounts are required.

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

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

Two short sentences, zero filler, with the action front-loaded and the constraint following immediately. Nothing could be removed without losing 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?

The tool is simple (one required parameter) and annotations carry the idempotency/safety story, so the definition is nearly adequate. The gap is the absence of an output schema combined with no statement of the return value, plus no mention of prerequisites such as account assignment, which matters for a flow-start operation.

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% with a single required 'id' parameter that is already documented as a string with minLength 1. The description's phrase 'by ID' adds no format, sourcing, or lookup guidance beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Start an Appmixer flow by ID'), which is unambiguous about the action taken. It does not, however, differentiate itself from nearby siblings such as stop_flow, test_flow, or trigger_component, so an agent must infer the boundary from names 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?

The precondition 'the flow must be valid and complete' implies the agent should validate first (there is a validate_flow sibling), but that route is never named. There is no explicit guidance on when to use this versus test_flow or trigger_component, leaving the choice 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?

The annotations already declare idempotentHint=true and destructiveHint=false, so the description adds essentially no behavioral context beyond restating the mutation. It does not say whether in-flight executions are terminated or allowed to finish, whether flow state/version is preserved, or whether the flow can be restarted with start_flow afterwards.

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 zero filler; the verb, scope, and keying parameter appear immediately. Nothing could be removed without losing 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 one-parameter mutation with no output schema and annotations covering idempotency and safety, the definition is close to sufficient. The remaining gap is behavioral: an agent cannot tell from this text whether stopping interrupts running component executions or how to resume.

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

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

Schema coverage is 100% and the single 'id' parameter is fully documented in the schema, so the description's 'by ID' phrasing adds nothing new. A baseline 3 is appropriate when the schema already does all the parameter work.

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

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

States a specific verb-plus-resource ('Stop a running Appmixer flow') and the keying parameter ('by ID'), which clearly separates it from siblings like start_flow, delete_flow, and get_flow_status. It stops short of naming an alternative, but the action itself is unambiguous.

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

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

The word 'running' implies the flow must currently be executing, which is the only usage condition conveyed. There is no explicit when-to-use versus start_flow/delete_flow guidance, no statement about what happens if the flow is already stopped, and no note on required permissions.

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

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

Annotations already declare destructiveHint=false and openWorldHint=true; the description adds useful context that the flow doesn't need to be running and that outputs per component are returned. However, for an open-world test execution it never says whether tested components perform real side effects (emails, store writes) or are sandboxed — the single most important behavioral question here.

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

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

Four short sentences, front-loaded with the action and its scope, then the input expectation, the return shape, and the usage rule. No filler or restated title.

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

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

With no output schema, the description compensates by stating that outputs per component are returned, and the multi-component scope is made clear. The remaining gap is side-effect semantics for an open-world execution, which an agent would need before running it on a live flow.

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 every parameter is already documented, including the payload/input_data distinction and the timeout bound. The description's 'Provide the input data the component should receive' only paraphrases the schema, adding no syntax or edge-case 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 — 'Test-run a single component (and its downstream graph) of a flow' — plus the key scope qualifier 'without starting the flow.' This clearly separates it from start_flow, validate_flow, and trigger_component.

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 'Use this to verify a flow works before start_flow,' naming the alternative and the selecting condition, and adds that the flow need not be running. It does not address when to prefer validate_flow or trigger_component instead, which are the closest competing siblings.

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

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

Annotations already declare openWorldHint=true and destructiveHint=false, and the description adds that the flow must be running and the HTTP method must match the trigger. However, it does not explain whether the call waits for completion, what response or errors look like, or whether repeated calls are idempotent, so behavioral disclosure remains limited beyond annotations.

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

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

Three tightly focused sentences front-load the action and follow with only the component-discovery and GET-alternative details needed to invoke it correctly. No redundant restatement of the schema.

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

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

For a four-parameter, open-world trigger tool, the definition covers the critical invocation facts: the flow must be running, component_id discovery, method matching, and the GET alternative. Response behavior is unspecified, but the core information needed to call the tool correctly is present.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description still adds meaning for method selection (POST default; match the trigger's method; GET goes elsewhere) and for locating component_id via get_flow, though it adds little about body beyond the schema's JSON object definition.

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 sentence states a specific verb (send a webhook request) and resource (trigger component of a running flow), and explicitly distinguishes the GET case by routing to read_component_trigger. It also names get_flow as the way to obtain component IDs, so an agent can select it without opening sibling 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 says to use this for POST (default), PUT, PATCH, DELETE and to use read_component_trigger when the trigger expects GET. It also gives the prerequisite that the flow must be running and tells how to find component_id via get_flow with include_descriptor=false.

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

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

Beyond the idempotentHint/destructiveHint annotations, it discloses the key behavioral trait that the supplied descriptor and custom_fields REPLACE stored values rather than merge, which is exactly the data-loss risk an agent needs to know. It also explains that validation runs on update and that a running flow is rejected unless forced.

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

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

Four sentences, front-loaded with the action, then the critical construction rule, then the failure condition. Every clause carries operational information; there is no restatement of the title or filler.

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

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

For a six-parameter mutation with a nested descriptor object and no output schema, this covers prerequisites, overwrite semantics, and the running-flow constraint. The one gap is what happens on validation failure (error shape, whether a partial write occurs), which the agent must discover by calling.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by telling the agent how to construct the 'flow' parameter (complete descriptor, reuse IDs, pull from get_flow) and by clarifying that force applies to running flows. It does not add meaning to 'description' or 'custom_fields' beyond the schema's own replacement note.

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

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

States a specific verb and resource ('Update an existing Appmixer flow'), names the mutable facets (descriptor and/or name), and adds that the flow is re-validated. This is clearly distinguishable from create_flow, clone_flow, and validate_flow in the sibling list.

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

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

Gives an explicit precondition and workflow: start from the current descriptor obtained via get_flow with include_descriptor=true, keep existing component IDs, and preserve untouched configuration. It also states the exclusion condition for running flows and the escape hatch (force).

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with that by framing the tool as a validation check rather than a mutation. It adds useful behavior beyond annotations: the check runs server-side, returns per-component errors such as wrong port names, missing required fields, and invalid variables, and acts as a gate before starting a 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?

Three short sentences with the core action front-loaded, followed by the error detail and the operational constraint. No filler or redundant 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 single-parameter read-only validation tool with no return schema, the description gives enough: what it validates, the nature of the errors returned, and the precondition for use. It does not specify whether validation is scoped to a specific version or requires particular permissions, but those gaps are minor here.

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

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

There is a single required 'id' parameter with 100% schema description coverage, so the schema already explains it fully. The description adds no additional meaning about the ID (format, source, or lookup), which matches the baseline of 3 when the schema carries parameter documentation.

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 ('Validate an Appmixer flow') and scopes it as 'server-side', which separates it from execution-oriented siblings like test_flow or start_flow. It also names the concrete outputs (per-component errors), so an agent knows exactly what the tool produces.

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?

'A flow must be valid to start' gives a clear precondition that ties this tool to the start_flow workflow, implying when to call it. It stops short of explicitly naming alternatives or when-not-to-use cases, so it is clear context rather than full routing guidance.

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