Activepieces

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

Annotations already disclose the operation is a mutation (readOnlyHint=false) that is non-idempotent and non-destructive, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond that: the new branch is inserted before the fallback branch, establishing ordering semantics. It does not disclose what happens on repeated calls or whether the flow must be in a draft 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, the core action front-loaded and the ordering constraint immediately after. Every sentence carries information 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 mutation tool with no output schema and full parameter coverage, the schema carries most of the burden, and the ordering note is a genuinely useful addition. However, the description omits likely-relevant context such as the effect of non-idempotent repeated calls (duplicate branches) and prerequisites on router step state.

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 all four parameters (flowId, routerStepName, branchName, conditions) are well documented in the schema, including the nested condition structure and operator semantics. The description adds no parameter syntax or format detail, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('Add a conditional branch to a router step'), which clearly separates it from ap_update_branch and ap_delete_branch. It does not, however, name those siblings or otherwise distinguish itself explicitly; sibling differentiation is left to inference from the verb.

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 statement of when to use this tool versus ap_update_branch, ap_delete_branch, or ap_add_step. The only hint ('Use ap_flow_structure to get valid values') lives in the schema's routerStepName field, not the description, so the description itself offers no routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the mutation profile is covered by structured data. The description adds that configuration can be folded into the same call, but says nothing about side effects on the flow, whether the flow must be published afterward, or the result of the call. 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, zero filler, with the core action stated first and the usage preference second. Nothing is repeated from the schema or annotations.

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

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

For a 15-parameter, nested-object, no-output-schema mutation tool, the description is short but the schema carries nearly all the necessary detail (required fields, enums, placement semantics, helper tools). What is missing is post-call behavior: whether the flow is auto-saved/published and what the tool returns.

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

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

Schema description coverage is 100% and the per-parameter text is unusually thorough (cross-references to ap_research_pieces, ap_flow_structure, ap_list_connections, expression syntax, continueOnFailure semantics), so the baseline is 3. The description only adds that input/auth/sourceCode are the optional inline-configuration trio, which is marginal value over 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 precise verb+resource ('Add a new step to a flow') and the second clarifies scope by noting the step can be configured inline in the same call. It is clearly separable from ap_update_step/ap_delete_step/ap_add_branch by name and verb, but the description never explicitly contrasts itself with those siblings.

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

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

The description offers a real preference rule ('Prefer PIECE actions and inline formula expressions over CODE'), but that guides stepType selection rather than tool selection. There is no statement of when to use ap_add_step versus ap_update_step, ap_build_flow, or ap_insert via other means, and no prerequisites (e.g., publishing, parent step existence) 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?

Annotations already declare non-read-only, non-idempotent, non-destructive, closed-world. The description adds real behavioral context beyond that: default sequential placement, loop nesting via parentStepName, the hard ROUTER limitation, and the formula-wrapping syntax. It stops short of stating authorization/connection requirements or what happens on duplicate flow names, which keeps it out of 5 territory.

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 core purpose is front-loaded in the first clause, and each subsequent clause carries a distinct rule (nesting, ROUTER exclusion, edit-alternative, PIECE-over-CODE). It is dense and long-winded in places, but no sentence is filler, so it stays efficient despite its length.

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

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

There is no output schema, so the definition owns the burden of describing the result; it never says what is returned (e.g., flow id) after creation, which is the main gap. Everything an agent needs to construct the call — step types, ordering, nesting, ROUTER deferral — is otherwise covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: the ordering model for the steps array, how parentStepName + INSIDE_LOOP combine, and the `ap-formula-v1::{…}::ap-formula-v1` inline-expression convention that appears nowhere in the JSON schema.

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

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

Opens with a precise verb+resource+scope: "Create a NEW flow from scratch in one call: trigger + steps." It goes further and explicitly carves out what it is not (not an editor for existing flows, not a ROUTER builder), which lets an agent separate it from ap_add_step / ap_update_step / ap_add_branch without opening their 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 when-to-use (build a whole flow in one call), when-not ("For EDITING an existing flow, do NOT rebuild it — use the granular ap_add_step / ap_update_step / ap_update_trigger instead"), a documented workaround for the unsupported ROUTER case, and a preference rule (PIECE + inline formulas over CODE). This is explicit routing guidance, not inference.

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

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

Annotations declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is already carried by structured data. The description adds nothing on top of that: it does not say what disabling actually does to in-flight runs, triggers, or schedules, nor that the operation is repeatable/safe to re-issue.

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 efficient sentence with the action front-loaded and zero filler. It is arguably under-specified for a destructive mutation, but nothing in the sentence is wasted.

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

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

For a small two-parameter mutation with full schema coverage and no output schema, the essentials are present, but the description omits the publish precondition and the downstream effects of toggling status, which are the pieces an agent would most need beyond the structured fields.

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 status enum is self-documenting ('ENABLED to activate, DISABLED to pause it'). The description's only added nuance is that flowId must point at a published flow, which is already implied by the body text, so baseline 3 applies.

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

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

The description gives a specific verb pair (enable/disable) and resource (flow), and the qualifier 'published' narrows scope. It does not, however, differentiate itself from adjacent siblings such as ap_lock_and_publish, ap_delete_flow, or ap_rename_flow, so an agent still has to infer the boundary.

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 prerequisite (e.g., that the flow must already be published), and no mention of alternatives for pausing/activating behavior. The 'published' qualifier implies a precondition but never states it explicitly.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds nothing beyond that: it does not say whether the new flow is empty or draft, what happens on name collisions, or 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?

A single front-loaded sentence with zero padding. It is efficient, though the brevity is partly under-specification rather than pure conciseness.

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 should indicate what a caller gets back (e.g., a flow ID needed to chain into ap_add_step or ap_build_flow). For a creation tool that is the entry point to a larger flow-authoring workflow, this gap matters.

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 both parameters are fully documented in the schema, including the non-obvious folderName ordering constraint. Baseline 3 applies since the description contributes no additional parameter meaning.

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

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

States a specific verb and resource ('Create a new flow'), which is clear on its own. It does not differentiate from nearby siblings such as ap_duplicate_flow, ap_build_flow, or ap_rename_flow, so an agent must infer which create-like tool applies.

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 offers no when-to-use, when-not-to-use, or prerequisite guidance. The only workflow hint (create the folder in an earlier step) lives in the folderName schema field, not the description.

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 idempotentHint=true and destructiveHint=false, and the description reinforces this by disclosing the get-or-create behavior, which is meaningful beyond the hint alone. It does not cover permissions, return payload shape, or what happens if the name collides with an unrelated folder, but with the safety profile already in annotations a 4 is warranted.

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 with no filler, front-loading the create-or-get behavior and then the sequencing instruction. Every clause carries actionable information.

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

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

For a single-parameter container tool with no output schema, the definition covers purpose, precondition, idempotency and the handoff to dependent tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds semantic role beyond the schema: folderName acts as the shared solution identifier that must be reused across ap_create_flow, ap_build_flow and ap_create_table. Format constraints (maxLength 255, minLength 1) 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 description gives a specific verb and resource ('Create a folder to hold one solution's flows and tables') and immediately clarifies the upsert nature ('or get it if a folder with that name already exists'). This distinguishes it cleanly from siblings like ap_create_flow and ap_create_table, which create the contents rather than the container.

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 exactly when to call it ('once before building a solution of several flows and tables') and names the downstream tools that consume the result (ap_create_flow, ap_build_flow, ap_create_table) along with the value to pass. The when-to-use condition and the follow-up chain are explicit, leaving nothing to inference.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered. The description adds the DATE/DATETIME storage-vs-display distinction, which is useful behavioral context, but says nothing about prerequisites, permissions, side effects, or the folderName timing caveat (which lives only in the schema).

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

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

Three tight sentences, front-loaded with the core action and then the type semantics. No filler, no restatement of the tool name, and the most consequential detail (type behavior) is not 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 create tool with no output schema, the description covers what is created and what the field types mean, and annotations cover the safety profile. It is still thin on usage context (when to create a folder first, how this relates to ap_manage_fields) and says nothing about what happens on success, but the structured fields carry most of the load adequately.

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 and the schema already documents name, fields, and folderName. The description nevertheless earns above baseline by clarifying the field type enum semantics, notably that DATE and DATETIME both hold ISO-8601 UTC timestamps while DATETIME additionally exposes time of day — meaning the schema does not fully convey.

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

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

The description states a specific verb and resource ('Create a new table with an initial set of fields') and scopes the operation with 'initial set', which distinguishes it from a field-management tool like ap_manage_fields. It does not, however, explicitly contrast itself with siblings such as ap_delete_table or ap_list_tables, so it lands just 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?

There is no direct when-to-use or when-not-to-use guidance, and no alternative is named (e.g., ap_manage_fields for later additions, ap_create_folder for placement). Some usage-relevant information is implied by the field-type semantics, particularly the DATE vs DATETIME distinction and the STATIC_DROPDOWN options, but the agent must infer when this tool is the right choice.

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, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds the meaningful failure constraint that the fallback/last branch cannot be deleted (and therefore that this call can fail), but says nothing about flow-state prerequisites or side effects.

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 hard constraint immediately after. Nothing is padded or 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 destructive, no-output-schema tool the safety hint and the fallback restriction are present, and the schema supplies full parameter detail. However, it omits prerequisites (e.g., whether the flow must be unpublished) and what happens to branches indexed after the deleted one, leaving real gaps.

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

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

Schema description coverage is 100% and each of the 4 parameters is documented in the schema, including the 0-based indexing and the approval prompt requirement. The description adds no parameter meaning beyond what the schema already carries, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a branch from a router step') plus a hard constraint, so the agent knows exactly what the tool acts on. It does not differentiate from siblings like ap_delete_step or ap_update_branch, which is the only gap.

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 sentence 'Cannot delete the fallback branch' is a constraint, not usage guidance. There is no statement of when to use this versus ap_update_branch or ap_delete_step, and any prerequisite discovery is only implied by the schema's pointer to ap_flow_structure.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the irreversible nature is covered there. The description reinforces it with 'permanently' and 'cannot be undone', and adds the scope detail that all versions are deleted. It does not contradict annotations, but adds limited context beyond them since the safety profile is already in the annotations; a mid-high score because the version-scope detail is genuinely additive.

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, front-loaded sentences with zero filler. The warning is concise and 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 single-parameter destructive tool with no output schema, the description covers the essential warning and scope. The only gap is not naming a non-destructive alternative, but the core information needed to call it correctly (what it does, that it's irreversible) 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?

Only one parameter, documented at 100% coverage in the schema ('The ID of the flow to delete'). With 0 params the baseline would be 4, and here the schema fully carries parameter meaning; the description adds nothing specific about flowId, which is acceptable given the schema coverage. This lands at baseline since the description does not need to compensate.

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 (delete) plus resource (flow) and states the scope (all its versions). Distinguishes cleanly from sibling delete tools like ap_delete_branch, ap_delete_step, and ap_delete_table by naming the specific resource.

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?

Clear context that this is a permanent, irreversible deletion of a flow, which implicitly tells the agent to prefer non-destructive alternatives (e.g., ap_change_flow_status) when deactivation suffices. However, it doesn't explicitly name an alternative or spell out when-not-to-use.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds 'Permanently', which usefully confirms there is no recovery path, but it says nothing about cascading effects, behavior on unknown IDs, or partial-failure semantics for a bulk operation.

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

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

A single front-loaded sentence with zero filler; the destructive intent is immediately clear. It is efficient, though arguably too terse to carry much operational detail.

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 bulk destructive tool with no output schema but fully documented parameters, the description is minimally viable. It omits details an agent would want before calling it, such as partial-failure behavior, whether deleted records can be restored, or return/confirmation shape.

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

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

Schema description coverage is 100%, so all three parameters (tableId, recordIds, displayName) are already documented in the schema itself. The description contributes no additional parameter meaning beyond the one-word ID-based scope, so the baseline 3 applies.

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

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

States a specific verb ('delete'), resource ('records'), and scope ('one or more ... by their IDs'), including the permanence qualifier. It does not differentiate itself from siblings like ap_delete_table or ap_update_record beyond the resource noun, 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 gives no when-to-use or when-not-to-use guidance, no mention of alternatives such as ap_update_record for modifying rather than removing data, and no stated prerequisites. The only routing hint ('Use ap_find_records to find it') lives in the schema, not the description.

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 safety profile is covered; the description nevertheless adds the non-obvious consequence that deletion destroys sample data, which is exactly the kind of side effect an agent needs. It does not mention irreversibility or permission requirements, so it stops short of 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: the action first, the routing caution second. No filler, and the most decision-relevant information is front-loaded.

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

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

For a destructive, no-output-schema tool, the description plus annotations cover the essential picture: what it removes, that it is destructive, and the safer alternative. Additional detail on cascading effects on branches or reversibility would complete it, but nothing critical is missing.

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

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

Schema description coverage is 100%, including the hint to resolve valid step names via ap_flow_structure, so the schema carries the parameter burden. The description adds no syntax or format detail beyond it, 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?

States a specific verb and resource ('Delete a step from a flow') and explicitly distinguishes itself from the sibling ap_update_step, so an agent can route without opening either schema. The scope (a step, not a flow or branch) is unambiguous.

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

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

Gives a clear preference rule: use ap_update_step to modify rather than deleting. It supplies the alternative and the reason, but does not spell out when deletion itself is the correct choice (e.g. removing an obsolete step) or any prerequisites such as needing the flow locked.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value by disclosing the blast radius — the deletion is permanent and cascades to all table data — which the annotations alone do not convey. It stops short of covering auth/permission requirements.

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

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

A single front-loaded sentence with no filler. The most consequential fact — permanence — is stated immediately.

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

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

For a destructive two-parameter tool with full schema coverage and destructive annotations, the description is nearly complete; the approval-prompt workflow is documented in the schema. A brief note on required permissions or confirmation would close the remaining gap.

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

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

Schema description coverage is 100%, so both parameters (tableId, displayName) are already documented well, including the approval-prompt requirement. The description adds nothing about parameters; baseline 3 applies.

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

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

States a specific verb (delete) and resource (table) plus the scope of destruction (all its data). It doesn't explicitly distinguish itself from siblings like ap_delete_records or ap_delete_flow, but the resource noun makes 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?

The description gives no when-to-use guidance, no prerequisites, and no mention of alternatives such as ap_delete_records for row-level deletion. The only routing help ("Use ap_list_tables to find it") lives in the schema, not the description.

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

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

Annotations cover the mutation profile (not read-only, not destructive, not idempotent), and the description adds important scope details: all steps and configuration are copied, but connections and sample data are not. This goes beyond annotations and helps the agent understand the effect. It does not mention return values or permissions, so not a 5.

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

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

The description is three compact sentences, front-loaded with the core action, then the copy scope, then the exclusion. Every sentence earns its place with no 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 duplication tool with annotations covering safety and a complete input schema, the description covers the key behavioral nuance (what is and isn't copied). Missing details about return value or error conditions are minor given the lack of an output schema, but the definition is nearly complete.

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

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

Schema description coverage is 100%, with both parameters well documented, including a note to use ap_list_flows for flowId. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb (duplicate) and resource (flow), and clarifies that it copies all steps and configuration. However, it does not explicitly differentiate this from sibling tools like ap_create_flow or ap_build_flow, leaving the agent to infer that this is for copying rather than creating from scratch.

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: use when you need a copy of an existing flow. There is no explicit guidance on when to choose this over alternatives such as ap_create_flow, nor are any prerequisites or exclusions 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, idempotentHint, and non-destructive behavior, so the safety profile is fully covered structurally. The description adds an operator enumeration and the notion of optional filtering, but nothing about execution behavior, result size, or unknown-field handling. 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 tight sentences, front-loaded with the core action. The operator list is somewhat redundant with the schema enum, which keeps it from a 5, but 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 read-only query tool with no output schema, the description should ideally say something about the shape/size of results or the effect of the limit. Instead it covers only input-side concerns, leaving the agent to infer return behavior entirely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the operator list already present as an enum in the schema and does not clarify ambiguous operators such as 'co' (contains?) or how value typing works for gt/lt. 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?

States a specific verb and resource: 'Query records from a table with optional filtering.' This clearly distinguishes it from the insert/delete/update record siblings in the list. It lacks any explicit naming of those siblings, 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?

There is no guidance on when to use this versus ap_delete_records, ap_insert_records, or ap_update_record, nor any note about pagination or how to handle large result sets. The only usage signal is the indirect 'optional filtering' phrase. Context is implied, not 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing the returned content and the three-valued configuration status (configured/unconfigured/invalid), which is not derivable from the schema or annotations. It does not mention error cases such as an unknown flowId, which keeps it short of a 5.

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

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

One dense sentence that front-loads the core purpose and lists the payload contents without filler. It is slightly long as a single sentence, but every clause adds distinct information, so nothing is wasted.

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

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

With no output schema, the description carries the burden of describing the return, and it does so concretely (tree shape, step type, config status, insert locations). Only minor gaps remain, such as behavior on an invalid flowId or tree depth/pagination limits.

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

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

Only one parameter (flowId), and schema description coverage is 100%, so the schema already documents it. The description adds no format, source, or resolution guidance for the id, so the baseline 3 for high-coverage schemas applies.

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

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

Specific verb (Get) plus resource (flow structure) with an enumeration of exactly what is returned: step tree, step type, configuration status, and valid insert locations. This distinguishes it from siblings like ap_add_step, ap_validate_flow, and ap_read_step_settings, which an agent could otherwise confuse it with.

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 mention that it returns 'valid insert locations for ap_add_step' implicitly routes the agent to call this before ap_add_step. There is no explicit when-not or comparison against ap_validate_flow / ap_read_step_settings, but the prerequisite context is clear enough to select the 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?

Annotations already establish readOnly/idempotent/non-destructive/open-world, so the safety profile is covered. The description adds meaningful behavior beyond that: what is returned, that trigger output paths are derived from sample data, and that auth is required to resolve dynamic dropdowns and dynamic property sub-fields. It does not explain pagination or failure modes, but those are largely irrelevant for a schema lookup.

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

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

Front-loads what is fetched, then the downstream usage, then the auth caveat. Two dense sentences with no filler, though the second sentence bundles several distinct behaviors and could be marginally tighter.

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

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

No output schema exists, and the description compensates by describing the return payload (AI description, idempotency hint, output field paths) and how to consume it downstream. For a 6-parameter lookup tool with nested input objects, this is close to complete, missing only error/empty-result behavior.

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

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

Schema description coverage is 100%, so every parameter is already documented with examples and cross-references. The description reinforces the auth-driven dynamic-resolution behavior, but adds little param syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get the input schema for a piece action or trigger') and enumerates the additional payload (AI description, idempotency hint, output field paths). This clearly separates it from siblings like ap_search_actions and ap_research_pieces, which locate actions rather than describe one 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 real context: use the AI description to pick the right action, reference output fields downstream as {{step['output'].path}}, and pass auth to resolve dynamic dropdowns. It also points to ap_list_connections and ap_research_pieces for inputs. It stops short of explicit when-not-to-use or naming an alternative tool like ap_resolve_property_options.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds value by disclosing what the payload contains (step outputs, errors, durations), which matters because there is no output schema.

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

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

One sentence, front-loaded with the verb and resource, no filler or redundancy. 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?

With no output schema, the description usefully previews the return content, which is the main gap it needed to fill. It is slightly thin on size/pagination behavior for large runs, but nothing critical 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?

Schema coverage is 100% on the single flowRunId parameter and the schema itself explains where to obtain the ID. The description adds no format or source detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (get results of a flow run) and enumerates what the result contains: step-by-step outputs, errors, durations. It implicitly distinguishes itself from the listing sibling, though it never names ap_list_runs the way the schema does.

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

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

Usage is only implied: retrieving detailed results for a run implies a prior listing step, and the schema description (not the tool description) supplies the 'use ap_list_runs to find it' routing. There is no explicit when-to-use versus ap_list_runs, ap_retry_run, or ap_test_flow.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows this is a non-destructive, non-idempotent write. The description's only added claim, "Max 50 records per call," merely restates the schema's maxItems=50 and says nothing about partial-failure behavior, duplicate handling, or 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 the core action front-loaded and no hedging or filler. The second sentence duplicates maxItems from the schema, so a sliver of it fails to earn its place.

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

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

For a write tool with no output schema, the description covers the action and the batch limit but omits error/partial-write semantics and confirmation of return behavior. Adequate to call correctly, but thin on what an agent should expect after invoking it.

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

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

Schema description coverage is 100%: both tableId and records are documented in the schema, including an example record and the externalId alternative. The description adds no syntax or format meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Insert one or more records into a table"), which is unmistakable and distinct from siblings like ap_update_record, ap_delete_records, and ap_find_records. It does not, however, explicitly name or differentiate itself from those siblings.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g., ap_update_record for existing rows), and no prerequisites such as needing a tableId from ap_list_tables. The schema infers a tableId reference, but the description offers no routing help.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds that the output enumerates provider names and model IDs, which is modest but real added context for a read tool. It does not mention auth/permission needs or whether unconfigured providers appear.

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 purpose and followed by use case and output shape. All three earn their place, though the first and third sentences partially overlap in describing what is returned.

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

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

For a no-required-param, read-only listing tool with full schema coverage and no output schema, the description supplies the missing piece — what the response contains (provider names and model IDs). An agent has everything needed to select and call it correctly.

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

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

Schema description coverage is 100%: the single `provider` enum parameter is fully documented, including the default behavior when omitted. The description adds nothing about the filter beyond what the schema already says, so the baseline 3 applies.

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

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

States a precise verb and resource ('List configured AI providers and their available models') and goes further to name the downstream purpose (discovering valid values for Run Agent steps). No sibling tool in the set covers AI provider/model discovery, so the tool is unambiguously distinguishable.

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

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

'Use this to discover valid provider and model values for configuring Run Agent steps' gives clear, actionable context for when to reach for this tool. There is no when-not guidance or named alternative, but none is needed since no sibling overlaps this capability.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false and closed-world, so the safety profile needs no restating. The description adds context annotations cannot: the key field returned (externalId) and its role in step auth. It stops short of describing other returned fields (status, pieceName, displayName).

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 what the tool does front-loaded and the reason it matters immediately after. 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 simple, side-effect-free list tool with full parameter documentation and no output schema, the description covers the essential return field an agent needs to chain into step configuration. It could note the other returned fields but 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 description coverage is 100% and each of the three filters (status, pieceName, displayName) is documented in the schema with auto-expansion and partial-match semantics. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource+scope ('List OAuth/app connections in the project') and adds the downstream purpose of the result ('externalId needed for the auth parameter on steps'). No sibling tool in the list also enumerates connections, so it is inherently distinguishable from the flow/step/record tools.

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

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

The second sentence gives real context for when this tool matters: you call it to obtain the externalId an auth parameter requires. It does not name an alternative tool or state when not to use it, but the usage condition is clear enough for an agent to act on.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the returned field list; it says nothing about pagination behavior or how results are ordered, which is mildly useful context but not rich 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?

A single front-loaded sentence with no filler. The verb, scope and payload are stated immediately and nothing is wasted.

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

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

For a read-only list tool with complete parameter documentation and full annotation coverage, the description is nearly sufficient; no output schema is needed since the returned fields are enumerated. The only missing element is guidance on result size/pagination given the 100/500 limit.

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

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

Schema description coverage is 100%, and the schema already documents name (partial match), limit (default 100, max 500) and the status enum. The description mentions no filtering behavior at all, so it adds no meaning beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('List flows') plus the scope ('in the current project') and even the returned fields (status, trigger type, published state). It is easy to distinguish from mutating siblings like ap_create_flow or ap_delete_flow, but it never explicitly contrasts with the closest read-side alternatives such as ap_flow_structure.

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 gives no when-to-use or when-not-to-use guidance and names no alternative. An agent cannot tell from this text whether ap_list_flows or ap_flow_structure is the right call for inspecting one flow's internals.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the scope is limited to the current project and each result carries flow/table counts. It omits any pagination or result-size behavior, which keeps it from a 5.

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

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

Two short sentences, zero filler, with the what-is-listed claim front-loaded and the usage hint second. Nothing is redundant.

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

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

For a zero-parameter, read-only list tool, the description supplies the scope and the shape of each result, which is nearly everything an agent needs. The lack of an output schema and the absence of any volume/pagination note are the only remaining gaps.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly describes a no-argument, project-scoped listing.

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 (folders) plus scope (current project) and the payload returned (flow and table counts per folder). This clearly separates it from ap_list_flows, ap_list_tables, and ap_create_folder 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?

Explicitly gives a use context: reuse an existing folder name rather than creating a near-duplicate, which implies it should be called before ap_create_folder. No named alternatives or when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already cover the safety profile: read-only, idempotent, non-destructive, and closed-world. The description adds useful context by disclosing the returned fields, including failed step info, which is valuable because no output schema is present.

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 two sentences, front-loaded with the core action and scope. Every sentence earns its place, with no wasted or duplicated 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 low-complexity list tool with full schema coverage and safety annotations, the description covers purpose, filtering, and returned fields. It does not restate schema defaults such as the environment behavior, but it is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the input schema fully documents limit, flowId, status, and environment. The description only says 'optional filters' and adds no syntax, default, or exclusion details beyond what the schema already provides, fitting the baseline 3.

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

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

The description states a specific verb and resource: list recent flow runs, with optional filters. It clearly distinguishes from ap_get_run by emphasizing a list rather than a single run, but does not explicitly name or compare against sibling tools.

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

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

The description implies usage by saying 'List recent flow runs with optional filters,' which gives an agent a clear context for when listing is appropriate. However, it provides no explicit when-to-use, when-not-to-use, or alternative-tool guidance against siblings like ap_get_run or ap_list_flows.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable non-obvious context: the dual-id model and which tool family consumes each id. It doesn't cover pagination or output format nuances beyond field/row-count mention.

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

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

Three sentences, all earning their place, with the core action and scope front-loaded and the id-routing guidance following. No filler.

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

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

With no output schema, the description correctly describes what comes back (fields and row counts) and explains how to use the returned ids. An agent has everything needed to call and apply the result.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool is high. The description appropriately spends its space on output shape instead of nonexistent 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 (List) and resource (tables) scoped to the current project, and specifies the returned content (fields name/type/id and row counts). It is clearly distinguishable from siblings like ap_create_table and ap_delete_table.

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 to discover tables before querying or modifying data, and routes the agent downstream by naming the record/field tools that consume the returned id. It also distinguishes the two identifier values (id vs externalId) and where each is used.

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

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

Annotations declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuine context beyond that: it discloses the three-part side effect (locks the draft, sets it as published, enables the flow) and the error-return behavior when the flow is not ready, both of which the 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?

Three short sentences, front-loaded with the core action and then the mechanics and error behavior. No filler, no repetition 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 mutation with no output schema, the description covers the action, its side effects, and failure signaling, and the annotations cover reversibility and idempotency. The only minor gap is that success return behavior (beyond errors) is not described, which is acceptable given the low 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?

There is only one parameter (flowId), and the schema already documents it at 100% coverage with a clear description. The description adds nothing about the parameter, so the baseline 3 applies when the schema carries the full load.

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

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

The description names a specific compound action (publish, lock, enable) on a specific resource (the current draft version of a flow), which is easy to distinguish from siblings like ap_validate_flow or ap_change_flow_status. It stops short of naming those siblings explicitly, but the operation described is unique enough that an agent can pick it out.

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 guidance on when to use this versus alternatives such as ap_validate_flow, ap_test_flow, or ap_change_flow_status. The phrase 'Returns validation errors if the flow is not ready' hints at a precondition, but the description never states whether validation should be run first or what to do on failure.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the 'Max 100 fields per table' constraint, which is useful context not present in annotations, but it doesn't describe permissions, reversibility, or side effects of rename/delete beyond what annotations imply.

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: the core operations are front-loaded, followed by a key constraint. 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 mutation tool with rich schema coverage and annotations that carry the safety profile, the description supplies the essential operation semantics and a field limit. It is largely complete for correct invocation, though it could add more context about prerequisites or the destructive nature of DELETE beyond annotations.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including conditional requirements (e.g., fieldId for UPDATE/DELETE, type for ADD). The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

The description uses specific verbs (add, rename, delete) and a clear resource (fields on a table), and the schema's operation enum reinforces this. It doesn't explicitly differentiate from siblings like ap_create_table or ap_delete_table, but the resource is distinct enough that an agent can tell them apart.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites, and no mention of related tools like ap_list_tables (which the schema references for fieldId). Usage is only implied by the operation enum.

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, idempotentHint=false, and readOnlyHint=false, so the agent knows DELETE is a mutating, non-idempotent, destructive operation. The description adds only the canvas-annotation context and never warns that deletion is permanent or that ADD requires position/content while UPDATE does not.

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 the action and resource front-loaded and zero wasted words. Nothing is repeated from the title or 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 7 parameters, nested position/size objects, no output schema, and rich annotations, the schema carries most of the burden and the description is adequate as a summary. However, it omits that different operations require different parameters and says nothing about the effect or reversibility of DELETE, leaving real gaps for a destructive multi-operation tool.

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

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

Schema description coverage is 100%, so width/height defaults, enum colors, noteId usage, and operation semantics are all documented in the schema. The description adds no parameter-level meaning beyond what the schema already states, so baseline 3 applies.

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

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

The description gives a specific verb triple (add/update/delete) and a clear resource (canvas notes on a flow), plus a one-line explanation of what notes are. It does not need to differentiate from siblings because no other tool in the list touches notes, but it also does not explicitly say so.

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

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

There is no guidance on when to use this tool versus alternatives, nor on prerequisites such as needing an existing flowId or the noteId required for UPDATE/DELETE. The second sentence only defines what a note is, not when to manage one.

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

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

Annotations already declare this as a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description adds a genuinely non-obvious side effect not present in the annotations: the folder is created when no folder has that name, and matching is case-insensitive. It does not say what happens if both parameters are supplied or if uncategorized=true is used on an already-uncategorized 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?

Two compact sentences with no filler: the primary action and its side effect come first, then the parameter constraint. Every clause carries distinct information and nothing repeats 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?

For a three-parameter mutation tool with no output schema and full annotation coverage, the description supplies the essential elements: the action, both modes, the side effect of folder creation, and the exclusivity rule. Minor gaps remain around error behavior for conflicting or redundant parameters, but nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description contributes real meaning the schema lacks: the mutual-exclusivity constraint between folderName and uncategorized, which is not expressed as anyOf/oneOf in the schema. That constraint is the single most important thing an agent must get right when calling this tool, so it deserves credit above 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 and resource ('Move a flow into a folder') and immediately covers both operation modes, including the non-obvious behavior that a missing folder is created. An agent can distinguish this from sibling tools like ap_create_folder or ap_list_folders 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?

The sentence 'Pass exactly one of folderName or uncategorized' gives an explicit, actionable usage rule that maps each mode to its purpose, and 'take it out of its folder with uncategorized=true' clarifies the second mode's intent. It stops short of naming a sibling alternative (e.g. ap_create_folder) for agents that only want folder management, 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context: content is returned untruncated, in contrast to ap_flow_structure. It omits any note on response size limits or pagination, which keeps it from a 5.

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

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

Two sentences, front-loaded with what is returned and immediately followed by the differentiating truncation detail and the alternative tool. No wasted words.

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

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

No output schema exists, so the description must indicate return content, which it does by enumerating source code, package.json, and input. Combined with the truncation disclosure and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, and the schema already documents both flowId and stepName, including a usage hint pointing at ap_flow_structure for valid values. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Read) and resource (full source code, package.json, and input of a CODE step), and explicitly scopes it to CODE steps. It distinguishes itself from siblings by naming ap_flow_structure and ap_read_step_settings, so an agent can pick correctly 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?

Clearly routes the agent: use this when you need untruncated CODE-step content, use ap_flow_structure when truncation is acceptable, and ap_read_step_settings for full settings of any step type. No explicit 'when not to use' or prerequisites, but the sibling contrast gives strong selection guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond the annotations: that output is untruncated versus ap_flow_structure's truncated piece input, and what fields are included. It stops short of return format or pagination details, keeping it at 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 sentences, front-loaded with the core capability and scope, then usage, then the CODE-step exception. Every sentence earns its place; no filler. Slightly dense enumerations but appropriately sized for the tool's complexity.

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 load of describing return content, and it does so by listing the settings categories returned. Combined with annotations covering the read-only safety profile and a 100%-covered schema, an agent has enough to invoke it correctly; only explicit return-shape detail is absent.

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

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

Schema description coverage is 100% and both params (flowId, stepName) are documented in the schema, including the stepName example and the pointer to ap_flow_structure for valid values. The description adds no parameter-level syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (a step's settings) with the exact scope 'full untruncated settings', and enumerates the contents (trigger piece input, action/trigger name, loop items, router branches, error handling). It distinguishes itself from ap_flow_structure and ap_read_step_code by name, so an agent can route correctly without opening other 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 states when to use it ('to see a step's current configuration before updating it') and names the conditions that select alternatives: ap_flow_structure for truncation reasons and ap_read_step_code for CODE step source. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the mutation and safety profile. The description adds nothing beyond that — no note on whether the rename affects references, permissions needed, or reversibility.

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 waste, but it is under-specified rather than genuinely concise — it earns its brevity by omitting information rather than by packing it.

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

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

For a low-complexity two-parameter tool with full schema coverage and a compliant annotation set, the minimal description is roughly sufficient to invoke correctly. It still omits any usage context, but nothing critical is missing for the call itself.

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

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

Schema description coverage is 100% and both parameters (flowId, displayName) are documented in the schema, so the baseline of 3 applies. The description contributes no additional parameter meaning.

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?

"Rename a flow." restates the tool name (ap_rename_flow) almost verbatim, adding no distinguishing detail beyond the name/title itself. It is accurate but qualifies as a tautological restatement rather than an independent statement of purpose.

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 indication of when to use this versus siblings like ap_change_flow_status, ap_duplicate_flow, or ap_update_branch, nor any prerequisites. No guidance is given at all.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: lookups "always return actions and triggers," each carries an AI guidance hint, and with forIntent "only the ones matching your intent carry their full description" while the rest are still listed. That asymmetry would be hard to infer from structured fields alone.

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, purpose front-loaded, then the three modes in priority order. The one flaw is redundancy: "so you pick the right action in one shot" is repeated verbatim in both the tool description and the forIntent schema field.

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 eight parameters, 50% schema coverage, and no output schema, the description does the important work of characterizing the return payload (actions, triggers, AI guidance hints, recommendedActions) and mode selection. Gaps remain around default behavior with no arguments, locale semantics, and suggestionType filtering.

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 50%, and the description meaningfully expands only two of the eight parameters (pieceNames, forIntent), mostly restating the schema's own examples. It does indirectly clarify why includeActions/includeTriggers are "searchQuery mode" only by contrasting the lookup modes, but locale, categories, and suggestionType remain unexplained in both places.

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 ("Research available pieces") and immediately breaks the tool into three distinct modes: pieceNames, searchQuery, and forIntent. An agent can tell what it retrieves. It does not, however, distinguish itself from the closely related siblings ap_search_actions, ap_search_triggers, or ap_get_piece_props, which an agent would need in order to choose correctly.

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 assigns modes to situations: "Use pieceNames for bulk exact lookup" vs "Use searchQuery for fuzzy discovery" vs "Pass forIntent ... so you pick the right action in one shot." That is real when-to-use guidance. It stops short of exclusions or naming the overlapping sibling tools (ap_search_actions/ap_search_triggers), which is the most likely routing ambiguity here.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful runtime behavior: resolution is sequential with prior values fed forward, and the call halts and returns options on the first property lacking a `selectedValue`. It also warns to use `value` rather than `label` from returns — useful context the annotations cannot express.

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

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

Three sentences, front-loaded with the mechanism, then the driving rule, then the value-vs-label caveat. Every sentence carries distinct information 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?

For a read-only, nullable-output resolution tool, the description covers the tricky parts an agent must get right (cascading order, the stopping condition, value-over-label). No output schema exists, and the description only gestures at the returned options structure, but annotations plus schema fill most remaining gaps.

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

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

Schema description coverage is 100%, so all six parameters (including the nested propertyChain items) are documented structurally. The description restates selectedValue's behavior but adds no format or syntax beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb+resource (resolve a chain of dependent dropdown properties) and the exact scope: it handles cascading fields by resolving each property sequentially, feeding prior values forward. This distinguishes it from the single-property sibling ap_resolve_property_options without needing 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?

Clearly states when to use it ('For actions with cascading fields, e.g. Spreadsheet → Sheet → Columns') and how to drive it (pass `selectedValue` for known values; the tool stops and returns options otherwise). It stops short of naming the single-property alternative explicitly, so an agent must infer the split from the description alone.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the return shape (options with labels and values/IDs) and the caller-side rule to submit the ID rather than the label — a real invocation hazard it warns about.

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

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

Three tight sentences, front-loaded with the action, then the return shape, then the usage rule. No redundancy or padding.

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

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

For a 7-parameter tool with a nested `input` object and no output schema, the description covers purpose, return shape, and the key value-vs-label rule, and the schema carries the parameter detail. It does not mention the parent-property/refresher mechanics (the `input` object) that a caller must understand, leaving a small gap.

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

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

Schema description coverage is 100%, so all 7 parameters are already documented in the schema, including the auth/parent-dependency semantics. The description adds only field-type context (DROPDOWN, example domains) and no syntax or format detail beyond the schema. 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?

Specific verb+resource: 'Resolve dropdown options for a single piece property', refined by naming the concrete field type (DROPDOWN) and examples (Slack channels, Sheets, email labels). It does not explicitly differentiate itself from the closely-named sibling ap_resolve_property_chain, so it falls short of the top band.

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 use case ('Use this to discover valid values for DROPDOWN fields') plus an operational rule ('Always use the `value`... not the `label`'). It offers no when-not-to-use condition or routing to ap_resolve_property_chain, so it stops short of a 5.

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

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

Annotations declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is already covered. The description adds the semantic distinction between resuming and re-running, but never warns that a retry re-executes side effects or is non-idempotent, so it adds only modest value beyond the structured data.

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

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

Two tight sentences, zero filler, with the core action front-loaded before the strategy breakdown. Every clause earns its place.

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

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

For a two-parameter mutation with no output schema and full annotation coverage, the description supplies enough to call it correctly. What is missing — whether a retry returns a new run identifier or runs asynchronously — is minor given the annotations carry the safety profile.

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

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

Schema coverage is 100% and the enum values are already documented in the property descriptions, including the ap_list_runs pointer for flowRunId. The description's strategy gloss largely repeats the schema rather than adding format or constraint detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Retry a failed flow run') and enumerates the two strategies, which cleanly separates it from siblings like ap_test_flow and ap_run_action. It stops short of naming an alternative, but the intent is unmistakable.

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

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

Makes the trigger condition explicit — the run must have failed — and the strategy sentence tells the agent which mode to pick and why. It does not state exclusions (e.g. don't retry a successful run) or point at a sibling, so it lands just under a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context — that execution is one-shot and leaves no saved flow — which is not conveyed by the annotations.

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

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

Two sentences with zero waste; the one-shot scope is front-loaded before the alternative routing to ap_build_flow.

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

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

For a side-effecting execution tool the description covers scope, ephemerality and the alternative path, and the schema covers parameter shape and auth. Nothing critical is missing, though return behavior is unaddressed (acceptable since no output schema exists).

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

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

Schema description coverage is 100%, with each of the four parameters documented (including input key-matching and the auth note for connectionExternalId). The description adds no parameter-level meaning beyond that, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Execute a single piece action once, without building or saving a flow') and immediately contrasts it with the flow-building path, so an agent can distinguish it from ap_build_flow, ap_add_step and the rest of the flow siblings.

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

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

It gives explicit when-to-use ('one-shot tasks like check my inbox or send one Slack message') and when-not-to-use ('For recurring/triggered work') and names the alternative tool ap_build_flow. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive; the description goes well beyond them by disclosing the keyword fallback when no embedding model is configured (with the literal 'mode':'keyword' marker), the possibility of an empty list rather than a forced match, ranking by semantic similarity, lightweight-row responses, and the 'connected' flag semantics.

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

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

Front-loaded with purpose, then behavior, then the workflow chain — every sentence carries information and none is filler. Sentences are dense and long, which slightly hurts scanability.

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

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

With no output schema, the description compensates by describing the return shape (ranked lightweight rows, connected flag, mode field) and the empty-result case, and it maps the tool into the broader action-execution workflow. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds operational meaning to pieceName ('optionally scope to a single piece') by tying it to the catalog-wide default. limit's max/default are left to the schema, but nothing is genuinely missing.

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

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

Specific verb+resource: 'Find piece actions by natural-language task description', with a concrete example. It is clearly distinguishable from siblings like ap_search_triggers (triggers, not actions) and ap_research_pieces.

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 frames itself as 'the discovery step' and names the exact follow-on chain (pieceName + actionName -> ap_get_piece_props -> ap_run_action). It also states the no-match behavior. It does not, however, contrast against the adjacent sibling ap_search_triggers, so an agent must infer when to prefer one search over the other.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the return shape (lightweight rows only, similarity-ranked), the empty-list-on-no-match behavior, the keyword-fallback mode when no embedding model is configured ('mode':'keyword'), and the `connected` flag meaning. These are real behavioral traits not derivable from annotations or schema.

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

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

Front-loaded with the core purpose and examples, then layers on ranking, fallback, flags, and the next step. It is dense but a single long paragraph; the fallback and next-step guidance could be split for scannability, but nothing is wasted.

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

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

No output schema exists, yet the description describes the return contract (ranked lightweight rows, mode field, connected flag, empty list) adequately for an agent to consume results. Combined with the downstream-tool pointer, an agent has everything needed to call and use this tool.

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

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

Schema description coverage is 100%, so the schema already documents query, limit, and pieceName. The description reinforces pieceName scoping and repeats the query example, but adds no new syntax or format detail (e.g. limit bounds or ranking effects). Baseline 3 is appropriate.

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

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

States a specific verb and resource (find piece triggers) plus the query semantics (natural-language description of when the flow should run), with concrete examples. It is clearly distinguishable from the sibling ap_search_actions, which searches actions rather than flow-starting events.

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 frames itself as the discovery step and routes the agent onward: 'take a result's pieceName + triggerName to ap_get_piece_props for its input schema.' It also sets expectations that no match is forced ('does not force a match') and that search may degrade to keyword mode, so the agent knows when not to trust semantic ranking.

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 safety is covered; the description adds the non-annotation fact that the call 'always returns the list of available projects' and that omitting the param clears state. That return/state behavior is genuine value beyond the structured fields, though it doesn't note what happens for an invalid projectId.

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 prerequisite fact, then the two call modes, then the return guarantee. No sentence is filler and nothing repeats the title.

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

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

With no output schema, the description supplies the missing return-value information, and with annotations covering safety and idempotency, an agent has everything needed to call this correctly. It covers prerequisite, invocation, and result.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema itself. The description's note about omitting projectId to clear and list projects largely restates the schema description rather than adding syntax or error semantics, 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 pair and resource (set/clear project context) and is unmistakably distinct from every sibling, which all operate on flows, steps, records, or tables. An agent can identify this as the session-scoping tool without opening the schema.

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

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

Explicitly states the triggering condition ('All tools require a project context to operate') and both invocation modes: with a projectId to select, without to clear. It doesn't name alternative ways to establish context, but for a prerequisite session tool this is clear, actionable guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one useful behavioral note — it returns instructions for the user rather than performing setup — but says nothing about format, length, or whether results vary by pieceName.

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 no filler, front-loading the action and then the return behavior. Slightly terse for a tool whose output semantics matter, but efficient.

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

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

For a two-parameter read-only lookup with no output schema, the description tells the agent what it gets back (steps to follow) which is the key missing piece an output schema would otherwise provide. No annotations conflict; nothing critical is omitted.

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

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

Schema description coverage is 100%, with both parameters documented in the schema including the enum and an example piece name. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource: 'Get setup instructions for connections or AI providers,' and clarifies it returns steps for UI follow-up. It is distinguishable from siblings like ap_list_connections, though it does not name which sibling to use in ambiguous cases.

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

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

Usage is only implied — an agent infers you call this when a user needs setup help for a connection or AI provider. There is no explicit when-to-use vs. alternative guidance, nor any mention of prerequisites or interactions with sibling tools.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description adds genuinely new behavioral facts beyond them: the test scope, the 120s wait ceiling, and that triggerTestData is persisted as sample data. It does not explain what the destructive aspect touches (e.g., flow state, published version), which is the main remaining gap.

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

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

Three short sentences, front-loaded with the core purpose and then the prerequisite and timing bound. No filler or restatement of the title.

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

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

For a mutating, non-idempotent test tool with no output schema, the description omits what a test result looks like (pass/fail, run ID to follow up with ap_get_run) and what state changes persist. It covers prerequisites and the mock-data path adequately, but the return/aftermath story is missing.

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

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

Schema description coverage is 100%, so flowId, displayName, and triggerTestData are already documented. The description reinforces when to supply triggerTestData (no sample data), which is a mild addition, but adds nothing about displayName or the flowId lookup beyond the schema's own pointer to ap_list_flows. Baseline 3 applies.

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

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

States a specific verb and resource ('Test a flow') and adds a scoping qualifier ('end-to-end in the test environment') that implicitly separates it from ap_test_step and ap_validate_flow. An agent can tell what this does without opening the schema.

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

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

Gives a real prerequisite ('Requires a configured trigger'), a bound on behavior ('Waits up to 120s'), and a conditional instruction for triggerTestData when no sample data exists. It does not name an alternative tool or state when not to use it, so it falls short of the top tier.

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

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

Annotations already declare the mutation/destructive profile, and the description adds genuinely useful behavior: the test executes all prior steps, not just the target, which warns of cascading side effects, and it discloses that triggerTestData is persisted as sample data. Return format is not described, but no output schema exists so that is a minor gap.

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

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

Three short sentences, each earning its place, with the core action front-loaded before the prerequisite and the conditional parameter hint. No filler or redundancy.

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

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

For a destructive mutation tool with full schema coverage and no output schema, the description covers the key things an agent needs: scope of execution, required trigger configuration, and when to supply test data. Only the success/failure response behavior is unaddressed.

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

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

Schema coverage is 100%, so all four parameters, including their descriptions and the displayName approval-prompt requirement, are already documented. The description adds only the conditional note on triggerTestData, which is marginal beyond the schema's own 'Useful when the trigger has no prior test data' text, warranting the baseline 3.

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

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

The description states a specific verb and resource — testing a single step within a flow — and clarifies scope with 'runs all steps up to and including the specified step,' which distinguishes it from a whole-flow test. It does not explicitly name ap_test_flow as the alternative, so it falls short of full sibling differentiation.

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

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

It gives a clear prerequisite ('The flow must have a configured trigger') and a conditional instruction ('Pass triggerTestData when no sample data exists'). It stops short of explicitly contrasting with ap_test_flow, so the agent must infer the alternative.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, so the agent knows this replaces conditions and is idempotent. The description adds that steps inside the branch are unaffected, which is useful context beyond annotations. However, it doesn't mention permission requirements or that conditions are fully replaced (that detail is only in the schema).

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

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

Two sentences, both earning their place: the first states the action, the second clarifies non-impact. Front-loaded with the primary purpose, no waste.

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

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

Annotations cover safety flags, schema covers parameters thoroughly, and no output schema means return values needn't be described. The description is complete enough for an agent to understand the tool's scope and side effects, though it could mention prerequisites like fetching the flow structure first.

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 parameters in detail, including the exact replacement semantics for conditions and the 0-based branchIndex with fallback restriction. The description adds no parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a clear verb+resource: update conditions and/or name of an existing router branch. The added clause 'Does not affect the steps inside the branch' clarifies scope. It does not differentiate from siblings like ap_update_step or ap_add_branch explicitly, but the verb/resource is specific enough.

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?

No indication of when to use this versus ap_add_branch, ap_delete_branch, or ap_update_step. Only the schema description for routerStepName hints at consulting ap_flow_structure, which is a prerequisite rather than usage guidance. Minimal context provided.

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

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

Annotations declare destructiveHint=true (writes are destructive), idempotentHint=true, and readOnlyHint=false. The description adds that only specified fields are changed, which is useful context about partial updates. However, it doesn't disclose what 'destructive' means here – e.g., whether it overwrites existing values, what happens to unmentioned fields, or any auth requirements. With annotations covering safety profile, the added value is moderate.

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 primary action, no redundancy. Every sentence contributes directly to understanding.

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 a mutation with a nested 'fields' object and destructive annotation, but no output schema. The description is very brief and doesn't cover error cases, return values, or side effects (e.g., whether it triggers automations). It's adequate but lacks details for safe invocation.

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

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

Schema coverage is 100%, so the schema already documents all three parameters fully, including examples for 'fields'. The description reiterates that only specified fields are updated, which is already in the schema's description for 'fields'. No new parameter semantics are added beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb ('Update') and resource ('specific cells in a record'), which is clear. However, it does not differentiate from siblings like ap_insert_records or ap_manage_fields beyond being an update operation; 'cells' is slightly informal for a record-based system.

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 (updating existing records, partial changes) but gives no explicit when-to-use guidance, no mention of prerequisites, and no alternative tools. It also doesn't warn against using it for creating records versus updating them.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the mutation/safety profile is covered. The description adds the patch semantics (unlisted fields are preserved), which is useful context beyond annotations, but it does not explain what the destructive aspect actually overwrites or any permission requirements.

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

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

Two short sentences, front-loaded with the core action and followed by the key invocation rule. No filler, though it is arguably under-specified rather than maximally efficient.

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

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

For a 12-parameter destructive update tool, the description is thin: it omits which settings are mutable, how step types map to parameters (LOOP/PIECE/CODE), and that ap_flow_structure/ap_read_step_settings help resolve values. The exhaustive schema compensates substantially, keeping it at a minimum-viable level.

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

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

Schema description coverage is 100% with rich per-parameter docs (auth, sourceCode, continueOnFailure, etc.), so the schema carries the full parameter burden. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Update an existing step's settings'), which clearly distinguishes it from creation/removal siblings like ap_add_step and ap_delete_step. However, it never explicitly names or contrasts with those siblings, leaving differentiation to inference.

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?

'Provide only the fields you want to change' gives genuine partial-update (patch) guidance on how to invoke the tool. But it offers no when-to-use vs alternatives, no mention of ap_read_step_settings to inspect current values first, and no prerequisites.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered. The description adds no further behavioral context, such as what happens to an existing trigger, whether auth is required, or how destructive replacement is handled.

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 wasted words. It is structurally clean, though its brevity leaves obvious content gaps rather than being a model of concise completeness.

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

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

For a destructive mutation tool with six parameters and no output schema, the description provides almost no operational context. The schema and annotations cover parameters and safety, but the description omits usage, prerequisites, and behavioral effects expected for an update trigger 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 description coverage is 100%, so the six parameters are fully documented in the schema. The description adds no parameter meaning, but the baseline is 3 when the schema carries this burden.

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

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

States a specific verb ('Set or update') and resource ('trigger for a flow'), making the core action clear. However, it does not distinguish this tool from nearby siblings such as ap_update_step or ap_add_step beyond the word 'trigger'.

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 gives no when-to-use guidance, no prerequisites, and no alternatives. It does not explain how this differs from ap_update_step, ap_add_step, or ap_search_triggers, leaving routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description nevertheless reinforces it with 'without publishing or running anything' and then enumerates the actual checks performed (step validity, template references, empty branches, Call Flow target/input/response compatibility, table/field existence). It stops short of describing the failure report format or whether it can be slow on large folders.

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 single most important fact (no publishing, no running) and organized by mode. It is dense with nested parenthetical detail, which is justified by the breadth of checks but does make it one of the longer descriptions.

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 validation tool with no output schema, the description covers both invocation modes, the exact scope of checks, and the workflow position relative to ap_lock_and_publish. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining what each parameter's validation mode actually inspects, which is meaningful for choosing between flowId and folderName. It does not add format constraints beyond the schema's minLength/maxLength.

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 (validate) and scope (one flow by flowId, or every flow plus interconnections in a folder by folderName), and immediately distinguishes itself from ap_test_flow and ap_lock_and_publish by clarifying it publishes/runs nothing. An agent can tell it apart from the many other ap_* tools without opening a schema.

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

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

Explicitly names the triggers: before ap_lock_and_publish, and after assembling a multi-flow/table solution. It also names the alternative it replaces ('instead of inspecting them by hand') and routes between the two modes (flowId for one flow, folderName for a whole solution).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds the non-obvious behavioral promise that validation 'Returns field-level errors without modifying any flow.' It does not describe error shape or which configs are out of scope, but this is solid added context beyond the annotations.

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

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

Two tight sentences, behavior first (returns errors, no mutation) and routing second (use before update calls). No filler, no restated name, front-loaded with the key semantic fact.

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 10-parameter validation tool with no output schema, the description covers purpose, safety, and call ordering, and the schema covers the field-conditionality. It could say more about the return/error format since there is no output schema, which is the only meaningful gap.

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

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

Schema coverage is 100% and the schema descriptions for the 10 parameters (stepType enum, per-type fields like sourceCode, packageJson, loopItems) are rich and conditional. The description adds nothing about parameters, so the baseline 3 is correct: 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?

Specific verb (Validate) plus resource (step configuration), and it explicitly distinguishes itself from siblings by naming ap_update_step and ap_update_trigger as the operations to run afterward. The read-only, error-returning nature of 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?

States the exact when-to-use condition ('before applying it', 'before calling ap_update_step or ap_update_trigger') and makes the alternative path explicit. An agent knows precisely when to reach for this tool versus updating directly.

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