Final POS – Custom POS Builder

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

Annotations already declare destructive=true, openWorld=true, and non-idempotent, so the safety profile is covered. The description adds genuine delegation context beyond that: it runs as the connection's user, on its company, within allowed packs, and can perform writes (creating products, deploying apps). It stops short of spelling out failure modes or result formatting, 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?

Front-loads the core action, then scope, then the when-to-use/alternative split, then the continuation hint. Every sentence earns its place with no padding.

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

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

For an agent-delegation tool with no output schema, the description covers purpose, scope, permissions context, usage routing, and continuation. It could say more about what a 'finished answer' looks like or how failures surface, but it is complete enough to invoke 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%, including the meaning of both task and conversationId, so the schema carries the parameter burden. The description's mention of passing conversationId to continue a thread merely restates the schema, adding no new syntax or constraints. 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 action ('hand a task in words to Finai... get its finished answer') with the concrete resource (Final's own AI agent). It explicitly contrasts itself with the sibling tool family by describing that it uses Final's tools internally, so an agent can tell it apart from call_tool or individual hub_* 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?

Gives explicit when-to-use ('multi-step merchant jobs you would rather describe than orchestrate') and names the alternative condition ('call tools directly when you need the raw data'). Also instructs on thread continuation via conversationId, 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real context: it is an indirection layer that can invoke tools not present in the listing, it enforces a read-only filter, and argument shape is defined by the target tool rather than this one. It does not say what happens if a write tool name is passed or whether the target tool's own permissions still apply, which is the 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 action and scope, then the read-only constraint, then the argument contract. Every clause carries information; nothing is restated 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?

For a meta-dispatch tool with no output schema, the description covers everything needed to invoke it correctly: what it does, what it refuses, where the sibling for writes lives, and where to find the argument schema. Nothing material is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds meaning beyond the schema: 'name' must be a full gateway name of a read-only tool, and 'arguments' must conform to that target tool's own input schema (obtainable via find_tools). That clarifies the dynamic, non-obvious contract of the arguments object, which the schema alone does not.

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

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

States a specific verb and resource ('run a read-only tool from any allowed pack by its full name') plus a concrete example (hub_find_low_stock), and its dispatcher nature is unmistakable. It distinguishes itself from call_write_tool directly, so an agent can route without opening schemas.

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

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

Explicitly names when to use this tool (read-only tools, including unlisted ones) and when not to (tools that change data go through call_write_tool), and points to find_tools as the source of the target tool's argument schema. Both the routing condition and the setup step are stated, not inferred.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior beyond them: a validation gate that rejects non-write tools, and the convention that arguments must conform to the target tool's own schema as returned by find_tools. It stops short of describing failure behavior or partial-application semantics for destructive operations.

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 load-bearing: the capability, the acceptance gate plus alternative, then the argument convention. The routing information is front-loaded and 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?

For a meta-dispatch tool with no output schema and a fully documented 2-parameter schema, the description covers the essential unknowns: which tools it will accept, where the argument contract comes from, and which sibling to use instead. It could still say what happens when a rejected tool name is passed, but nothing critical to a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that 'name' is the gateway name of an unlisted write tool, and it explains where the 'arguments' object's shape comes from (the target tool's own input schema, obtainable via find_tools). That resolves the main ambiguity of an open additionalProperties object.

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

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

The description states a concrete verb set (creates, changes, deletes, sends, deploys) and the resource (any allowed pack tool, addressed by full gateway name like hub_update_product), and explicitly frames itself as the unlisted counterpart to call_tool. An agent can distinguish it from call_tool and from find_tools without opening any schema.

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

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

It gives an explicit acceptance rule ('Only tools find_tools marks as writes are accepted') and an explicit alternative with the selecting condition ('read-only tools run through call_tool'). It also points to find_tools as the way to discover the tool and its schema, so both when-to-use and how-to-find 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, destructiveHint=false, and idempotentHint=true, so safety is largely covered. The description adds real behavioral value by clarifying blast radius: tools are only hidden from tools/list and remain callable via call_tool/call_write_tool, which answers the main agent worry about breaking access.

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 action and its effect, with no filler. Every clause carries information.

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

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

For a one-parameter, no-output-schema tool the description covers the action, its scope, and the recovery path for affected tools. The remaining gap - how to obtain valid pack names - is real but narrow.

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

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

The single parameter has 0% schema description coverage, so the description must compensate, but it never explains what a 'pack' identifier is, its format, or where to discover valid values (e.g., via list_packs). The array-of-strings input is left semantically opaque.

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

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

States a specific verb (remove) plus resource (packs) and, crucially, the non-obvious scope of the effect: removal from tools/list for this connection. This lets an agent distinguish it from enable_packs/list_packs without opening any schema.

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

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

The rationale ('to keep the list short') implies when to use it, but there is no explicit when-to-use or when-not-to-use guidance and no mention of the inverse sibling enable_packs. Usage must be inferred from the purpose statement.

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=true, so the safety profile is covered. The description adds genuinely new context beyond that: the change is 'remembered' (persisted) and the client refreshes its tool list, which tells the agent a re-listing side effect follows the call.

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

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

Two short sentences, front-loaded with the effect on tools/list and followed by the constraint and side effect. No filler, though the parenthetical '(remembered)' is slightly terse for a property as important as persistence.

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

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

With no output schema and a single fully-documented parameter, the description covers the essentials: the effect, the constraint, persistence, and the client-side refresh. It stops short of stating error behavior for non-allowed packs or whether the addition merges with already-enabled packs, which is the main 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?

Only one parameter and schema description coverage is 100%: the schema already says it is an array of required pack ids sourced from list_packs. The description adds nothing about id format, max size, or what happens if a mix of allowed and disallowed ids is supplied, 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 states a concrete verb and resource: it adds pack ids to the tools/list for 'this connection'. Combined with the name enable_packs and the sibling pair disable_packs/list_packs, an agent can tell what it does, though the 'tools/list' phrasing is protocol jargon that takes a moment to parse.

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

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

Usage is implied rather than stated: 'Only allowed packs can be listed' hints that disallowed packs will not take effect, and the schema points to list_packs as the id source. There is no explicit when-to-use versus disable_packs, no prerequisite about how packs are made 'allowed', and no statement about behavior on an invalid id.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false). The description adds scope ('every allowed pack') and, importantly, the shape of the result — matching names with pack, listed status, and whether they mutate data. No output schema exists, so this return-value disclosure earns real credit.

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, zero filler, with the search intent and examples front-loaded. The final sentence is over-compressed — 'or enable_packs to list its pack' reads ambiguously about whose pack and in what order — costing a point.

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 return-value burden and does so adequately (names, pack, listed flag, mutating flag). Remaining gap is the unmentioned limit/cap behavior, which matters for a discovery tool where matches can exceed 40.

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 50%: query is documented in-schema and reinforced by the plain-language examples, which is genuinely additive. However, limit (1–40, default 12) is undocumented in both schema and description, and there is no mention of what happens when more than `limit` tools match.

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 (Search) and resource (every allowed pack, for tools) plus the matching dimension ('by what you want to do'), with three concrete query examples. This is clearly distinguishable from the ~150 domain siblings, which all act on catalog data rather than discovering 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?

Names the downstream alternatives explicitly — call_tool for read-only matches, call_write_tool for writes, enable_packs to list a pack. The routing is stated but compressed and lacks a stated when-not (e.g. if you already know the tool name, skip this).

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, but the description goes well beyond them: it discloses that the widget files land under src/widgets/<blueprint>/, that a restorable checkpoint and builder-chat note are persisted 'like write_flow_files', that selfPersisting tables are provisioned automatically possibly under org-scoped names, that extension-owned tables are reported separately, and that secrets produce fill-in prompts with values never crossing MCP. The 'restores on re-apply' behavior is meaningful context for a destructive-hinted tool.

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

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

Front-loaded with the core action and byte-exact/no-transcription constraint in the first sentence, then layers the important caveats in a logical order. It is dense and somewhat repetitive (multiple 'never ... yourself' warnings), but nearly every clause carries a real routing or safety 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 complex, mutation-capable tool with no output schema, the description defines what comes back (a manifest with paths, export names, props, an import block — never the code), how tables/extension tables/secrets are surfaced, and the persistence side effects. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is only 40% across 5 params, so the description carries more burden. It explains picks well (shape {blueprintId, widgetId} and their origin) and the hubToken provisioning purpose is covered by the schema itself, but `note` and `agent` get no added meaning and flowId is left implicit. It partially compensates rather than fully.

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

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

States a specific verb and resource (COPY vetted blueprint widgets into a flow as real files) and explicitly distinguishes itself from siblings by naming list_blueprints/search_blueprints as the pick source and get_blueprint as the thing NOT to re-type from. An agent can tell it apart from flow_write_flow_files and flow_create_flow_from_blueprint without opening any schema.

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

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

Gives explicit alternatives and routing: obtain picks from list_blueprints/search_blueprints, compose screens by importing the returned manifest paths, adapt via a small write_flow_files edit rather than a wholesale rewrite, and never re-type code from get_blueprint. It also states re-applying restores vetted contents. This is unusually complete when/when-not guidance.

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

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

Annotations only flag destructiveHint=true; the description goes far beyond by disclosing atomicity ('nothing written' on bad resolutions), that the plan is recomputed server-side, the exact ordered effects (checkpoint, merged tree landing, update-pointer re-stamp, custom-table provisioning, secret fill-in requests), and that adopt mode is undoable via the checkpoint. This is unusually rich behavioral context for a destructive mutation.

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

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

Front-loads the imperative action and the resolutions contract before the long ordered effect list, so the callable facts come first. The run-on paragraphs are dense but nearly every clause carries distinct operational meaning; only minor tightening is possible.

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, multi-effect tool with no output schema and low schema description coverage, the description supplies everything an agent needs: prerequisites, atomicity guarantees, the adopt-mode branch, and the side effects. Nothing material is missing.

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

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

Schema coverage is only 33%, and the description compensates by fully specifying the resolutions shape ({path, contents} with the COMPLETE merged file, or {path, delete:true}) and the adopt flag contract (requires adopt:true with NO resolutions). The agent, hubToken and note params remain undocumented, so it falls short of complete coverage.

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

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

States a specific verb+resource ('Apply the update') and immediately ties it to its counterpart 'get_upstream_update', making clear what this tool does and how it differs from the read-only sibling. An agent can distinguish it from flow_get_upstream_status/get_upstream_update without opening any schema.

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

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

Explicitly gates invocation on a prior review ('the update reviewed with get_upstream_update') and names the alternative path when the review reported adoptMode: true. It does not spell out when *not* to call it (e.g. no pending upstream update), but the working context is clear.

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 mark this as non-read-only but non-destructive, and the description adds real context beyond them: the action makes your work visible to the flow's owner in their chat rail, which is a meaningful side effect. It still omits whether the attach requires ownership, is idempotent, or can be detached.

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, with the primary action front-loaded ahead of the secondary tip about log_message. The parenthetical is helpful rather than filler, though the sentence is slightly dense.

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

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

With no output schema and only thin annotations, the description covers the main effect but leaves gaps an agent would want: the meaning of the 'agent' parameter, behavior when already connected, and any permission requirements.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It implies flowId via 'EXISTING flow' but says nothing about the 'agent' parameter, leaving half the inputs undocumented in both schema and prose.

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

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

The description gives a concrete verb and resource ('Attach this agent session to an EXISTING flow as a chat in the builder's rail') and states the visible effect. It differentiates from creation siblings by capitalizing EXISTING, though it never names flow_create_flow as the contrasting tool.

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

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

Usage is implied rather than stated: the emphasis on 'EXISTING flow' steers away from creating a new one, and the tool points at log_message for narration. There is no explicit when-not-to-use, no prerequisite (e.g. needing a valid flowId or ownership), and no stated alternative for starting fresh.

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

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

Annotations only declare it is a non-read-only, non-destructive, non-open-world write. The description adds far more: creation is immediate and org-wide (visible to every station and flow), it can be plan-gated with an error that should be surfaced rather than retried, names are normalized to kebab-case, and the table is synced offline to stations. It also flags a confirmation requirement for unintended persistence.

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

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

Front-loads the core action and then layers constraints, so the important guidance appears early. It is dense and somewhat run-on (multiple clauses per sentence, some restatement of the kebab-case rule already in the schema), but nearly every sentence carries a distinct operational instruction rather than filler.

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

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

For a write tool with no output schema, the description covers the full lifecycle an agent needs: reuse checks, blueprint-collision avoidance, org-wide scope, offline behavior, plan/permission failure handling, and credential exclusion. Nothing material to calling it correctly 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 only 50%, and the description adds meaning for the two required params ("name + typed columns", kebab-case normalization) and how generated code reads/writes rows. However, hubToken and description are never mentioned, and the field type enum / reference-linkage semantics are left entirely to the schema, so it does not fully compensate for the coverage gap.

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

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

Opens with a specific verb+resource ("Create a new custom data table") and immediately scopes it with the schema shape (name + typed columns). It is trivially distinguishable from siblings like flow_update_custom_table, flow_list_custom_tables, and flow_request_secret, which the description names outright.

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 ("USE THIS for any data the app must keep — loyalty stamps, waitlists, bookings, inventory logs") and when not to (credentials → request_secret). It routes the agent to list_custom_tables for reuse and search_blueprints to avoid duplicating tables a blueprint already provisions, with the precise failure mode ("a lookalike would sit dead") spelled out.

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

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

Annotations only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: the flow appears in the Miami builder immediately, the agent session is attached as a chat, and it returns a flow id plus a builder deep link. Still silent on permissions/org scoping and any rate or naming constraints.

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

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

Purpose is front-loaded in the first clause, followed by behavior, parameters, and routing in a logical order. Slightly chatty in places ('It appears in the Miami builder immediately, with this agent session attached as a chat'), but no sentence is purely 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?

Covers the essentials for a 9-param creation tool with no output schema: what it creates, the immediate side effect, the return value (flow id + deep link), the get_scaffold prerequisite, and the start_build alternative. Gaps are minor — org/permission requirements and most optional theme knobs go unqualified.

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

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

With schema description coverage at 33% across 9 params, the description should carry more weight. It does add useful framing for the theme group ('theme knobs seed the live palette') and clarifies `device` with examples and a cross-reference to set_flow_device, but title, agent, and the fonts/shape/theme nuance remain undocumented here. Partial compensation only.

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 ('Create a new, empty flow (app build)') and immediately scopes it as agent-authored ('for YOU to write the app into'). It distinguishes itself from siblings: 'empty' contrasts with flow_create_flow_from_blueprint, and the closing line names start_build as the different path for merely-described apps.

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?

Names an explicit alternative for one case ('For an app the user merely DESCRIBED, use start_build') and a prerequisite ('Call get_scaffold before writing files'). It implies but never explicitly excludes flow_create_flow_from_blueprint, so the when-not coverage is not fully complete.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false), disclosing that screens/navigation/command-frame wiring are copied byte-exact, custom tables are re-created under THIS organization's names with names that must be kept, and that a fill-in request is raised for each secret read. It also warns that the result names tools not to call and that flowId cannot redirect the copy.

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

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

Purpose and sibling routing are front-loaded and nearly every sentence carries a distinct instruction, which is justified for a high-consequence one-shot operation. It is nevertheless verbose, with all-caps emphasis and some restatement ('it is the finished deliverable, not step one' / 'do NOT preview, validate, edit or extend 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 13-parameter, nested-object mutation tool with no output schema and low schema description coverage, the description still conveys the critical behavioural contract: what gets copied, what gets re-created, what causes an error, that the operation is terminal, and what the returned report line means. Nothing an agent needs to avoid misusing it appears 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 only 46%, and the description compensates well for the highest-risk parameters: it explains how to obtain blueprintId (search_blueprints), why flowId errors out, and what supersedesFlowId does (and does not) affect. However it adds nothing for the eight appearance/infra parameters (color, fonts, shape, theme, palette, customColors, agent, hubToken), so the gap is only partially closed.

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 (create a NEW flow by copying an FBB, defined inline as 'a Final Business Blueprint: a whole app') and immediately contrasts it with the sibling start_build and the search path search_blueprints({ kind: "fbb" }). An agent can tell this apart from flow_create_flow, flow_apply_blueprint_widgets and flow_get_blueprint 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?

Explicit when-to-use ('when the user asked YOU to copy one' vs an app merely DESCRIBED), names the alternative for each case (start_build, apply_blueprint_widgets), and states the hard exclusion that an FBB cannot be merged into an existing build. The terminal instruction ('THE COPY ENDS YOUR TURN') also tells the agent what not to do afterwards.

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 mutation profile is covered. The description adds real value beyond that: engine-owned paths are rejected (a guarded constraint) and the deletion is recorded as a checkpoint plus chat note, which is non-obvious side-effect behavior an agent wouldn't infer from annotations.

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

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

Three short sentences, each earning its place, with the core action front-loaded before the path restriction and side-effect notes. 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 destructive 3-parameter mutation with no output schema, the description covers the action, a guard condition, and side effects, which is decent. However it omits reversibility/undo behavior, permission requirements, and any return/error detail beyond the engine-path rejection.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. 'By path' and 'a flow's tree' give partial semantics for the paths array and imply flowId, but the 'agent' parameter is completely unexplained and no path syntax/format is given. Coverage of the three parameters remains thin.

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

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

States a specific verb (remove) plus resource (files in a flow's tree) and the scoping mechanism (by path). It clearly contrasts with the sibling read/write pair, flow_read_flow_files and flow_write_flow_files, since 'remove' names the delete operation distinctly.

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 establishes the delete context and notes that engine-owned paths are rejected, but it never explicitly says when to choose this over flow_write_flow_files or what prerequisites apply. Usage is implied by the verb rather than stated.

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

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

Goes well beyond the annotations: enumerates exactly what blocks a deploy (failing build, hardcoded credential), what does not (guardrail/type findings), the reason credentials block (build is redistributable), the implicit credential provisioning behavior, and the changelog auto-draft side effect. Annotations only give the generic destructive/openWorld flags; this text supplies the operational reality.

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

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

Front-loaded with the core action, then blockers, then credential mechanics, then changelog. Dense but every clause carries information; the final credential-fallback sentence is slightly long but justified for a tool whose main failure mode is missing auth.

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 publish with no output schema and partial param coverage, it covers prerequisites, blockers, side effects and auth. It does not say what a successful deploy returns (version identifier/URL) or whether the previous live version is replaced, which are minor but real omissions.

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 25% (only hostingToken documented), so the description must compensate — and it does for changelog ('omit and the release notes are drafted for you') and hostingToken (escape-hatch semantics beyond the schema's wording). flowId and version are left to the schema/pattern, which is the one small gap.

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

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

States a specific verb+resource ('builds the app in a server sandbox ... publishes the dist to Final web-hosting as a new live version'), with the two constituent steps spelled out. It routes the agent away from sibling tools by naming validate_flow, request_secret, log_message, open_in_builder and write_flow_files where relevant.

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?

Explicit when-to-use (CI/agent workflows, direct deploy), when-not (guardrail/type findings don't block; run validate_flow first if you care), and alternatives (open_in_builder + Launch tool when no credential is available). The hostingToken escape hatch is framed as an override, not the default path.

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

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

Annotations cover the safety profile (readOnly, non-destructive), and the description adds substantial behavioral context beyond them: whole-flow blueprints return the screen manifest without file bytes by default, instantiation copies server-side, includeFiles is audit-only, and `tables` lists bound custom tables. This is unusually 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?

Dense but front-loaded: the mode ('INSPECTION ONLY') leads, followed by purpose, routing, anti-pattern, and the includeFiles caveat. Every sentence earns its place and no clause is redundant.

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

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

With no output schema, the description still explains the return shape (tables list, manifest-without-bytes default, file bytes only under includeFiles). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the params — and it does for includeFiles ('pass true only to audit the source') and gives provenance for id ('from list_blueprints'), plus documents the returned `tables` field. The only gap is that id's expected format is not specified.

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

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

States a specific verb and resource — read a blueprint's overlay code by id — and explicitly distinguishes itself from the write/apply path. The opening 'INSPECTION ONLY' immediately frames it against flow_apply_blueprint_widgets and flow_create_flow_from_blueprint.

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

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

Gives explicit when-to-use (understand how a blueprint works), when-not-to-use (to actually use it, apply instead), names the two alternative tools by name, and adds a strong anti-pattern warning against re-typing code into write_flow_files with the reason why.

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 the safety profile is covered by structured data. The description adds that the probe is 'authoritative server-side' and returns logs, but does not explain logSeconds behavior, timeout/rate behavior, or what the health result contains.

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

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

A single front-loaded sentence that states the primary function first and the auxiliary log snapshot second. No filler, though it is a bit compact given the two undocumented parameters.

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 does carry the burden of conveying return content, and it does so at a high level (health status + log snippet). However, the unexplained logSeconds parameter and the absence of any indication of the health response shape leave clear gaps for a diagnostic 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 0% for two parameters. The description never mentions flowId and only indirectly gestures at logSeconds via 'short snapshot of recent dev-server logs', without clarifying that it bounds the log window (1-20s). It fails to compensate for the missing schema descriptions.

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 ('server-side health probe of the flow's preview sandbox') plus a stated secondary output (recent dev-server logs). It is clearly a status/read tool, distinguishable in intent from siblings like flow_start_preview and flow_stop_preview, though it does not name them explicitly.

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

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

The parenthetical 'useful to diagnose a red screen or crash' implies when to reach for it, but there is no explicit when/when-not framing and no comparison to alternatives such as flow_start_preview or flow_sync_preview. Usage is suggested rather than specified.

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/openWorldHint=false/destructiveHint=false, and the description goes well beyond them: it warns that engine-owned files are re-asserted verbatim (never write them), and that certain runtime contracts compile and preview fine but fail on a real device, naming concrete traps (money in minor units, first-load handshake, getX unwrapping, tender semantics). That is unusually rich behavioral context.

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, followed by a dense but informative enumeration, then the imperative call-to-action. It is long but every clause carries distinct information; the packed runtime-contract list is the only mild density cost.

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 does so thoroughly (engine-owned files, baseline package.json contents, file rules, runtime contracts), while annotations already cover the safety profile. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already lists the accepted device values plus the fallback behavior for unrecognized input. The description adds the param's intent ('for layout guidance'), which the schema does not state, so it contributes a little beyond the structured field.

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+resource (retrieve the scaffold contract every Final flow app is built against) and then enumerates the contract's contents, so an agent knows exactly what it gets. It is clearly distinguishable from siblings like flow_get_blueprint or flow_lookup_engine_component, which serve different lookup purposes.

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 timing ('Call this once before writing any files') and a conditional ('pass `device` for layout guidance'), which is strong usage direction. It stops short of naming alternatives or stating when not to call it, so it is not a full 5.

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

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

Annotations already establish the safe-read profile (readOnlyHint, destructiveHint=false), and the description goes well beyond them: it enumerates every return branch of update.status with meaning ('available'/'current'/'unknown'/'gone'), notes the DELETED and un-shared edge cases, explains the FBB parent staying reachable, and states that non-snapshot copies return update: null.

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

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

Front-loaded with the core question, and the dense status enumeration is necessary information rather than padding. The nested parentheticals make it slightly heavy to parse, but 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so completely, including the null case and each status meaning. An agent has everything needed to call and interpret 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?

Schema description coverage is 0% for the single flowId parameter, and the description never defines it. The name is self-evident (the flow to check), so the practical gap is small, but the description adds no semantic detail beyond what is already obvious from the parameter name.

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 question the tool answers ('Has the build this flow was copied from released a newer version?') plus the two sourcing cases it covers (a listing clone and an FBB build). It is clearly distinguishable from the sibling flow_get_upstream_update, which it names as the follow-up for reviewing an available update.

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

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

Gives a concrete trigger ('safe to call whenever the user asks about updates') and routes the agent to flow_get_upstream_update when status is 'available'. It does not spell out when-not to call or the cost relative to other checks beyond 'cheap', but the guidance is clear and actionable.

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

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

Annotations already declare a safe read (readOnly, non-destructive), yet the description adds substantial context beyond them: exactly what is returned (releases, clean changes, conflicts with base/ours/theirs), the resolution contract, and the meaning of adoptMode and upToDate edge cases.

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, then the return shape, then the resolution contract. The prose is dense and long but most sentences carry distinct operational content; it could be trimmed but nothing is clearly redundant.

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

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

With no output schema, the description carries the full burden and does so: it enumerates return fields (releases, added/changed/removed paths, conflict base/ours/theirs contents) and covers both adoptMode and upToDate terminal states.

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

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

Schema coverage is 0% and the description never explains flowId, so it does not fully compensate for the gap. However flowId is self-evident from the tool's name and sibling conventions, keeping this at a baseline adequacy rather than a failure.

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 clearly: 'Review what an update from the original build would change,' framed as a read operation 'shaped for an agent.' It is readily distinguishable from the sibling apply_upstream_update (which it routes to) and flow_get_upstream_status.

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 strong next-step guidance ('Then call apply_upstream_update with exactly one resolution per conflict') and explains branch conditions via adoptMode and upToDate. It does not explicitly contrast with flow_get_upstream_status, but the when-to-use context is otherwise clear.

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 confirm readOnly=false and destructive=true, and the description adds substantial context beyond that: installs skip companies that already have the extension so the call is retry-safe, the action is deliberate and org-visible, per-company failures are collected rather than thrown, and installState returns installed/partial/none. This is exactly the idempotency and error-semantics detail 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?

Scope and destructive intent are front-loaded, and the closing sentence packs failure handling, outcome field, and its enum values efficiently. It is dense and oriented toward maximal information rather than tight brevity, but no sentence is filler.

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

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

With no output schema, the description carries the return-value burden itself and does so: it explains that per-company failures come back in the result and that installState summarizes the org-wide outcome. Prerequisite discovery, confirmation requirements, and post-install next steps are all 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% and the schema already documents extensionId's source ('the `id` from a list_extensions result — org or public source') and hubToken's fallback role, so the description's restatement adds little. Baseline 3 applies since the schema carries 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 plus an explicit scope qualifier: 'Install an extension ORG-WIDE ... on EVERY company in your Final organization (demo companies included)'. This cleanly distinguishes it from the single-company sibling hub_install_extension and from read-side siblings like flow_list_extensions.

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

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

Gives an explicit precondition ('call this ONLY when they explicitly asked for the extension' / 'confirm with your user'), a prerequisite step ('Find the id with list_extensions'), and follow-up routing ('inspect them with list_extension_surfaces'). An agent knows both when to call it and what to do next.

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

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

Annotations only declare a safe read (readOnlyHint, destructiveHint=false, openWorld=false); the description goes well beyond them by enumerating the returned fields, explaining the side effect of selfPersisting blueprints (tables are provisioned in the organization automatically, some extension-owned), and warning never to create a table a blueprint already covers. That is exactly the kind of consequence detail annotations cannot carry.

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

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

Front-loaded with the action and the pre-check guidance, and the return-field list plus kind taxonomy are both load-bearing for a tool with no output schema. It is dense and heavy on capitalization/emphasis, and a couple of clauses (the parenthetical functionality list, the restated 'never create a table for a feature it covers') could be trimmed without loss.

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-required-param listing tool with no output schema, the description supplies everything needed: what comes back per blueprint, what selfPersisting implies, the two kinds and which sibling tool consumes each, and how to narrow the result. No material gap remains for an agent deciding whether and how to call 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 0%, so the description must carry the single enum parameter, and it largely does: it identifies 'widget-set' as the default returned, 'fbb' as complete apps used with create_flow_from_blueprint, and 'any' as both. It never explains the fourth enum value, 'whole-flow', leaving one value's meaning undocumented 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 ('List EVERY vetted, type-checked blueprint available to reuse') and immediately scopes what a blueprint is (working functionality, not just screen layouts). It also distinguishes itself in the same breath from search_blueprints, get_blueprint, apply_blueprint_widgets and create_flow_from_blueprint, so an agent can route correctly without opening any sibling schema.

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

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

Gives an explicit when ('Check the catalog BEFORE creating custom tables or hand-rolling a capability') and names two alternatives with the condition that selects them ('To find the best match for a specific capability instead of scanning the whole catalog, use search_blueprints'). It also notes get_blueprint's role as read-only inspection, 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 readOnlyHint=true and destructiveHint=false, yet the description still adds meaningful behavioral context: tables sync across stations and work OFFLINE, they are the only sanctioned persistence (browser storage is rejected by validate_flow), and some blueprint-owned tables are invisible here. It does not disclose result size, pagination, or ordering, which keeps it short of a 5 for a listing endpoint.

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

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

Front-loaded with the core action, then layered caveats in descending priority. The sentences each carry information, though the domain primer on what custom tables are and the closing renderClient API note are somewhat tangential to a pure listing call, making it longer than strictly necessary.

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 stating what is returned ('tables with their column schemas') plus the important caveat that the list can be incomplete for selfPersisting blueprints. Combined with annotations covering the safety profile and full schema coverage on the one parameter, an agent has everything needed to call this correctly.

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

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

There is a single optional parameter (hubToken) with 100% schema description coverage, so the schema already explains it fully. The description adds no parameter-level detail, which is the expected baseline of 3 when the schema does the heavy lifting and the parameter is a fallback auth token.

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+payload: 'List your organization's custom data tables with their column schemas.' It is clearly distinguishable from siblings flow_create_custom_table, flow_update_custom_table, and flow_list_extension_custom_tables, which the description implicitly scopes away from by talking about org-owned tables.

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 ('Call this before create_custom_table to reuse an existing table instead of duplicating one') and routes to alternatives for adjacent needs (search_blueprints for new functionality, lookup_command_frame for runtime data access). It even covers the when-not case: a selfPersisting blueprint's tables may be absent, and 'their absence is never a reason to create lookalikes.'

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

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

Adds genuine behavioral context beyond the annotations: the empty-list-plus-note behavior for public/other-org extensions, and how the returned tables are consumed at runtime via renderClient.getCustomTableData / upsertCustomTableData, plus a grounding pointer to lookup_command_frame. 'Read-only. Does not write files.' largely restates readOnlyHint, which is why this is a 4 rather than a 5.

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

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

Front-loaded with the purpose and the runtime-consumption rationale before the constraints, and no filler sentences. It is a single dense paragraph with stacked parentheticals, which costs a bit of readability.

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

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

No output schema exists, and the description compensates by describing the returned content (table name plus typed columns) and the empty-list case. Combined with annotations that cover the safety profile and a fully documented schema, an agent has everything needed to call and interpret 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 coverage is 100%, so both parameters (hubToken, extensionId) are already documented in the schema, including the same 'id from a list_extensions result' note. The description adds no format, constraint, or edge-case detail about the parameters themselves, 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?

Specific verb (List) plus resource (an extension's registered custom tables) with the return shape spelled out as 'table name + typed columns'. It also distinguishes itself from two siblings: flow_list_custom_tables (org's non-extension tables) and flow_list_extensions (source of the id). An agent can route correctly without opening any schema.

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

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

Explicit prerequisites ('Pass the extension's id from list_extensions'), an exclusion ('Only the org's OWN extensions expose their tables'), and a named alternative for the other case ('the org's non-extension tables come from list_custom_tables'). It even states the outcome when the precondition fails: an empty list with a note.

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 read-only, but the description adds genuinely new behavior: public results need no hub credential, a note flags when the org-owned side is unavailable, results are relevance-ranked and capped to genuine matches (so an empty list means no capability exists), and publicTotal reports marketplace row count. This is rich context beyond the safety hints.

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

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

Purpose and scope are front-loaded, and the sentences about ranking, empty-list meaning, and routing all earn their place. It is dense and long, with minor redundancy in the closing 'Read-only. Does not write files.' that repeats the annotation.

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 return burden and does so: entry fields (id, label, category, short description, source), the org/public split, and publicTotal are all described. Nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: query is ranked against label, category, and blueprint vocabulary and capped to genuine matches, and omitting it browses the catalog with skip/limit paging. It goes beyond restating the schema fields.

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

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

States a specific verb (List) and resource (extensions available to the org plus the public marketplace) and immediately distinguishes scope from the inspection/install siblings. An agent can tell this apart from install_extension and list_extension_surfaces without opening any schema.

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

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

Explicitly routes: use this to 'suggest, inspect, or install', inspect results with list_extension_surfaces / list_extension_custom_tables, and install org-wide with install_extension ONLY when the user explicitly asked. Both the alternative tools and the condition that selects them are named.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so "Read-only. Does not write files" is largely redundant. The description earns credit by disclosing behavior annotations can't: auth resolution differences between org and public extensions, and how to interpret the `requirementsMd` field. No pagination or error behavior is mentioned.

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

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

Front-loaded with purpose in the first sentence, and the rest is dense with actionable detail rather than filler. It is on the long side because return-field semantics and the build-vs-embed workflow are interleaved, but each 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 appropriately compensates by naming the surface fields and explaining the meaning of `requirementsMd`, plus credential handling. It is nearly complete for a small read tool; only pagination/volume expectations are unstated.

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

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

Schema coverage is 100% and both parameters are already documented in the schema, including that extensionId is "the `id` from a list_extensions result" and hubToken is a JWT fallback. The description's "Pass the extension's id from list_extensions" repeats that verbatim and adds nothing, 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?

Specific verb+resource+scope: "List the SURFACES an extension exposes — embeddable iframe injection points." It enumerates the returned fields (surfaceId, platform, type, url), which distinguishes it clearly from sibling read tools like hub_get_extension_surfaces or flow_list_extension_custom_tables.

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?

Explicit routing guidance: pass the id "from list_extensions," and a decision rule for results — prefer building natively when `requirementsMd` is present, embed `<ExtensionSurface>` only when it's absent, grounding via lookup_engine_component. It also names both credential paths (own hub extension vs public marketplace), which is exactly the when/how an agent needs.

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 read-only, non-destructive, closed-world profile, so the description only needs to add beyond that — and it does: result ordering, the visibility rule that Final staff additionally see Final's own flows marked owner: "Final", and the presence of an upstreamUpdate field on clones. It stops short of mentioning pagination or whether limit truncates the list.

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

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

Three sentences, front-loaded with the core action and scope, then the special-case visibility rule, then the follow-up routing. Dense but every clause carries information; the upstreamUpdate sentence is slightly tangential but still actionable.

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 does the work of naming returned fields (id, title, timestamps, live theme knobs, upstreamUpdate) and the owner marker, which is exactly what an agent needs to consume the result. The remaining hole is the undocumented limit/pagination 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?

The single parameter (limit, 1-100) has 0% schema description coverage and is never mentioned in the description. The "newest first" phrasing hints at ordering but gives no guidance on what limit controls or how to page through a large result set, so the description fails to compensate for the schema gap.

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

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

States a specific verb+resource ("List the flows (app builds)") and pins the scope to the caller's organization with an ordering guarantee ("newest first"). It also names the fields returned and clarifies the special-case owner value, so an agent can distinguish it from flow_create_flow and the flow_read/write file tools without opening schemas.

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

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

It routes the agent forward explicitly: "Use a flow id with the other tools, or create_flow to start fresh," and points clones at get_upstream_update / apply_upstream_update. That covers when to use this result and what to do next, but there is no explicit statement of when not to call it (e.g. a search/filter alternative).

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

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

Annotations already establish the safe read profile (readOnlyHint=true), but the description adds substantial non-structured context: no tool returns secret values, and generated code resolves secrets at runtime via renderClient.getSecretVal({ key }) with only key names shipping in the build. This is materially beyond what the annotations 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?

What-it-does is front-loaded, followed by usage cases and a runtime clarification. The parenthetical and closing sentence about runtime resolution are dense but genuinely useful for a secrets tool, though the final clause is slightly tangential to the act of listing.

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 explains what is returned (key names only), why that is safe, and how consumers use them at runtime. For a zero-required-param read tool, an agent has everything it needs to call this correctly.

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

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

Schema coverage is 100%, so the single hubToken parameter is documented in the schema itself (a JWT fallback for when the hub rejects the API key). The description adds nothing about it, so the baseline 3 for high coverage 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 precise verb and resource — listing the key NAMES stored in the organization's encrypted secrets vault — and immediately scopes what it does NOT return (never values). It is clearly distinguishable from siblings, particularly the referenced request_secret.

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

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

Gives two explicit when-to-use cases: (a) reuse an existing key rather than requesting a new one, and (b) poll whether a request_secret ask has been fulfilled. The alternative (request_secret) is named with the condition that selects it, so nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write-but-non-destructive profile is known. The description adds that the message is scoped to this session and keeps the builder timeline faithful, but says nothing about persistence, ordering, idempotency, or auth needs. 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, front-loaded with the action and resource, with no wasted filler. The second sentence adds rationale rather than redundancy, though it is slightly more prose than strictly needed.

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 4-parameter write tool with no output schema and zero schema-level parameter docs, the description covers role semantics but leaves flowId and agent undocumented. It is minimally viable but not complete.

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

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

Schema description coverage is 0%, so the description must compensate for all four parameters. It only gestures at 'role' (values already exposed by the schema enum) and says nothing about flowId, text format, or the optional agent parameter, leaving the majority of parameters unexplained.

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

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

Names a specific verb (record/log) and resource (a message in the builder chat), and clarifies the two roles it can carry. It does not compare itself to any sibling, but no obvious overlapping flow_* tool exists, so the purpose is still 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 clause about the user's request (role 'user') versus your own progress/summary (role 'assistant') hints at when each role applies, but there is no explicit statement of when to call this tool versus other builder-facing tools, and no when-not guidance.

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

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

Annotations only establish read-only/non-destructive, and the description adds substantially more: fabricated names fail on real devices, typed signatures outrank worked examples that are explicitly not typechecked, and results carry `traps` for known field gotchas. This is exactly the kind of consequence and reliability context 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?

Front-loaded with what the tool returns, then usage modes, then the authority caveat and traps note — no filler sentences. The prose is dense and could be split with the parameter modes listed tersely, but every sentence carries information an agent needs.

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

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

With no output schema, the description does mention the shape of results in part (traps) and where the data comes from, and it addresses the conflicting-authority problem that could otherwise mislead an agent. It stops short of describing overall result structure or limits, which is a minor gap for a read-only reference 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 0% across 8 parameters, so the description carries the full burden and largely meets it by explaining the intent behind method/entity/topic/field/query and the plural batch variants. It does not say what happens when multiple lookup keys are combined or how query matching works, leaving some ambiguity.

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 with unusual precision: 'version-locked command-frame API' covering renderClient signatures, CF* entity fields, pub/sub topics, and examples. The scope is narrow enough that an agent can tell it apart from the sibling lookup tools (flow_lookup_pos_api, flow_lookup_engine_component) by subject matter.

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 triggering condition ('ground every renderClient call in this before writing it — fabricated fields/methods fail on real Render devices') and maps each parameter mode to a distinct intent: single key for precise lookup, entity+field for existence checks, query for fuzzy search, plurals for batch. It never names or contrasts the sibling lookup tools, so the agent must infer which lookup to reach for.

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 the safety profile is covered by structured data. The description adds real context beyond that — that these helpers are re-asserted into every generated app and that lookups return props/signature — but says nothing about result size, latency, or what a miss returns.

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 dense paragraph, front-loaded with the verb and resource before the enumeration. The long component list is justified because exact membership is what the agent needs, but the sentence is packed and could have been split for scannability.

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

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

No output schema exists, so the description must carry return-value semantics; it does so at a high level ('exact props/signature'). Combined with the usage rules and mode selection, an agent has enough to call this correctly, though the shape of the returned signature data is unspecified.

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

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

Schema description coverage is 0% and neither parameter is documented in the schema, so the description carries the full burden. It does this credibly: name = precise lookup, query = fuzzy search, neither = list all. It stops short of giving format details (e.g. path-style vs bare component name).

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 ('Look up') and a well-defined resource ('x engine-owned ./final/* helper') and then enumerates the exact component surface (Button, Card, Dialog, usePrint, Barcode, etc.), so an agent knows exactly what it will retrieve. It is clearly distinguishable from sibling lookups like flow_lookup_command_frame and flow_lookup_pos_api, which target different surfaces.

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 strong prescriptive guidance: compose screens from the primitives, import the rest, and stop hand-rolling buttons/cards/dialogs, printing, station-home, barcodes or splash. It also routes the agent between modes (name for precise lookup, query for fuzzy, neither to list all). It does not explicitly contrast itself against sibling lookup tools, so it falls short of a full 5.

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

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

Annotations only declare readOnly/non-destructive/closed-world, so the description carries the interesting behavior and does it well: online-only dependency, network egress from the station, failure whenever connectivity drops, and the warning not to place it in the sale path. One mild tension is openWorldHint=false against an 'ONLINE-ONLY' framing, but the network-egress sentence describes calls made through the documented API rather than this lookup itself, so it is not a genuine contradiction.

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

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

Front-loaded with the purpose and return shape, then the routing rule, then the constraint — a sound order. It is dense and long-ish (roughly five clauses), and a couple of parenthetical enumerations could be trimmed, but essentially every sentence carries decision-relevant content.

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

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

No output schema exists, yet the description states what the lookup yields (method/path, request fields, response shape, worked fetch example), which parameters select which result granularity, the alternative tool, and the operational constraint. For a 3-param read-only lookup, nothing needed to call it correctly is missing.

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

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

Schema coverage is 0% and the schema gives bare string types, so the description must compensate and largely does: 'Pass resource to list a domain, operation for one endpoint, or query for fuzzy search' assigns distinct semantics to all three parameters and disambiguates resource vs operation vs query. It does not document accepted resource/operation identifiers or formats, but the three-way distinction is the key information an agent needs.

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 (look up) and resource (the Final POS REST API) and enumerates exactly what it returns: endpoint method/path, request fields, response shape, and a worked example. It also explicitly distinguishes itself from the sibling flow_lookup_command_frame and from command-frame for live POS data, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use (admin/management operations command-frame cannot express: products/variants/categories, customers, outlets/stations/tax tables, webhooks), when-not (never in the sale path; command-frame is ALWAYS first choice for live POS data), and the failure mode to plan for (network egress that fails offline; degrade gracefully). This is close to a complete routing rule.

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 the safety profile is covered without the description's help. The description adds genuine context beyond that — that the output is a link consumed by a human owner who can restore checkpoints and deploy via the Launch tool. It omits practical traits an agent would want: link lifetime/expiry, any permission requirement to generate it, and whether the link is single-use.

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

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

It is a single sentence, but a padded one: 'The recommended way to finish' is promotional framing, and the parenthetical inventory (validation gates, listing media, changelog, version history) describes the Launch tool rather than this tool's behavior. The actual fact — it returns a deep link into the builder — could be front-loaded more cleanly.

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

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

For a one-parameter read-only tool with no output schema, the essentials are mostly present: what it produces (a deep link) and who consumes it (the owner, in the builder). Missing pieces are the undisclosed flowId semantics and the return shape (is the link a plain string?), which matter because there is no output schema to fall back on.

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 one parameter, flowId, and schema description coverage is 0% — the schema alone tells the agent nothing about what the id refers to. The description only indirectly gestures at it via 'this flow,' with no statement that flowId is the flow to be opened, nor any format/example. With low coverage the description is expected to compensate and it largely does not.

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

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

The description states a specific outcome: it returns 'a deep link that opens this flow in the Miami builder.' An agent can tell this is a hand-off/link-generation tool rather than a deploy or preview tool. It does not, however, name or contrast itself with any sibling (e.g. flow_deploy_flow, flow_get_preview_status), so differentiation is left 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?

'The recommended way to finish' implies this is called at the end of a flow authoring session and hands control to the owner, which is useful context. But it gives no explicit when-not guidance and never mentions alternatives such as flow_deploy_flow or flow_validate_flow, so the agent must guess at the boundary between this and the deploy path.

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 the useful detail that listing is 'cheap' versus fetching contents, but says nothing about sizing, errors, or what the tree contains.

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 with zero filler; the core purpose comes first and the parameter guidance follows 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 simple two-parameter read tool with annotations covering the safety profile and no output schema to explain, the description supplies everything needed to invoke it correctly in either mode.

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

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

Schema description coverage is 0%, so the description must compensate, and it does so well for `paths` (omit vs pass semantics and cost). It says nothing about `flowId`, though its meaning is largely inferable from the tool name.

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: reading a flow's generated source tree. An agent can distinguish it from write/delete siblings by the verb, though the description never names flow_write_flow_files or flow_get_scaffold to draw the boundary explicitly.

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

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

Clearly explains the two invocation modes: omit `paths` to list paths (cheap), pass `paths` to fetch contents. This is practical when/how guidance for the parameters, but it offers no guidance on when to prefer this over sibling tools like flow_get_scaffold.

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

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

Annotations only declare non-readonly/non-destructive; the description goes far beyond by enumerating the concrete effects (builder header, list_flows, open_in_builder, Deerlake catalog, updatedAt bump) and the deployment consequences (hosted web app retained, next deploy_flow publishes next version). This is exactly the mutation context an agent needs.

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

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

Front-loads the scope, then the deployment behavior, then the exclusion. Every sentence carries distinct, non-redundant information with 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 and only weak annotation coverage, the description fully covers effects and side effects, so an agent understands the outcome. The remaining gap is parameter-level guidance (flowId, agent) for a tool with three undocumented parameters.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it never names flowId or the agent parameter and only obliquely implies that title is the new name. The 120-char limit and required/optional status are left entirely to the schema.

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

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

States a specific verb and resource ('Rename a build (flow)') plus the authoritative scope ('across the platform in one call'), which separates it from the many other flow_* tools. An agent can identify this as the dedicated rename operation without opening the schema.

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

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

Explicitly carves out what this tool does NOT do and names the alternative ('Does NOT edit the app source: rename a hardcoded old name yourself with write_flow_files'). It also tells the agent when the rename is safe for a deployed build (hostname and version history unchanged).

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 only non-readonly, non-destructive, closed-world. The description goes far beyond that: it takes no secret value, no tool ever returns one, the human types into a masked builder input, the value lands in an encrypted vault, and the code must degrade gracefully until the key exists. That is exactly the operational context annotations cannot carry.

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

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

Front-loaded with the core action, then justified with the why, the runtime contract, and the post-call steps; nearly every sentence carries new information. It runs long and leans on caps-lock emphasis and a dense final sentence, which costs it the top mark.

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

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

For an 8-parameter, no-output-schema tool, the description covers the full lifecycle: why the call is needed, that no value flows through the tool, how generated code consumes the key, the degradation requirement, and the required follow-up (notify the user, poll list_secret_keys). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 75%, so most parameters are self-documented; the description still adds real meaning by tying 'key' to runtime consumption via renderClient.getSecretVal({ key }) and by implying the credential is never passed in. It does not explain hubToken, agent, docsUrl or provider beyond their schema text, which is the only gap.

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

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

States a specific actor, action and resource: it asks the flow's owner to enter a third-party credential into Final's encrypted vault. It also implicitly separates itself from flow_list_secret_keys, which it names only as a polling detector, so an agent can tell the requesting tool from the reading tool.

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 supplies when to use it (a credential is needed and must not be hardcoded), why not to inline it (builds are distributable and validate_flow/deploy_flow block hardcoded secrets), and what to do afterwards (tell your user to open the builder link and poll list_secret_keys). Alternatives and follow-up actions are explicit rather than inferred.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), yet the description adds substantial non-obvious behavior: the { results, note? } return shape, the meaning of selfPersisting, the fact that apply_blueprint_widgets auto-provisions the blueprint's own tables, the 'NEVER create a table for a covered feature' constraint, and that applied widgets stack on top of rather than replace the current build.

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 'what' and the RUN THIS FIRST directive, and every sentence carries actionable information. It is dense and long with heavy capitalization emphasis, which slightly hurts scanability, but there is little pure 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 search tool with no output schema, the description supplies the return shape, the ranking semantics, the follow-up action (apply_blueprint_widgets) and its provisioning side effects, and the fallback when no match is found. Nothing an agent needs to invoke or act on the result is missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains slot/surface as result narrowers and limit as a cap with default 10, but omits the `kind` enum (widget-set/fbb/whole-flow/any) entirely and gives no guidance on the enum values for slot/surface. Query semantics are only implied by the plain-language matching example, so compensation is partial.

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 (semantic search over the blueprint catalog) and explains the ranking mechanism (meaning, not shared words) with a concrete example. It explicitly distinguishes itself from the sibling flow_list_blueprints ('Prefer this over list_blueprints when you know what you need'), so an agent can route between them without opening either schema.

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

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

Explicit when-to-use ('RUN THIS FIRST — before creating custom tables or hand-rolling a capability'), when-not ('Low match scores across the board mean no vetted blueprint fits — only then build that piece from scratch'), and the alternative (list_blueprints). It even prescribes the query strategy: one search per distinct feature rather than a single broad query.

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, openWorldHint=false, but the description adds genuinely non-derivable behavior: previews idle-stop on their own, calling stop_preview frees resources sooner, the URL is public HTTPS and pre-pinned to a mock dataset (maker's pick, else vertical's). It does not cover auth/permission needs or concurrency behavior when a preview is already live beyond the parenthetical 'reconcile a running one'.

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 primary action and return value are front-loaded, and the lifecycle guidance follows in sequence with no filler sentences. It is somewhat dense with em-dashed parentheticals (e.g., 'sushi, not restaurant') that add flavor but mild reading overhead.

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 covers the return value (public HTTPS URL), the dataset-pinning rule, the sync trigger, and the resource lifecycle, which is what an agent needs to invoke it correctly. Remaining gaps are the undocumented flowId and the relationship to the sibling preview-status/sync tools.

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

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

Schema description coverage is 0% and the single required parameter flowId is never explained in the description. The text refers to 'this flow's mock dataset' and 'the flow's current files' but never states what flowId must contain (ID vs name) or where to get it, so the description does not compensate for the documentation gap.

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

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

Specific verb+resource with return value stated: 'Boot the flow's server-side preview sandbox (Vite dev server)... and return its public HTTPS URL'. It names the sibling it is not in the lifecycle case (stop_preview) and the follow-up trigger (call again after write_flow_files). It stops short of disambiguating from flow_sync_preview and flow_get_preview_status, despite the title's '(or sync)' overlapping with a dedicated sync sibling.

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

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

Gives clear operational context: open the URL in a browser, call again after write_flow_files to sync, and call stop_preview when done to free resources sooner. That is real when-to-use guidance with one explicit alternative. It omits any routing guidance versus flow_sync_preview/flow_get_preview_status, so the agent must guess which of the overlapping preview tools to pick.

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 (destructiveHint=true, readOnlyHint=false), so the description's job is to add context. It does: it discloses that resources are freed and, usefully, that the next start_preview incurs a cold boot, a restart-cost trait not present in the annotations. It does not explicitly state that live preview state is discarded.

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, purpose front-loaded ahead of the consequence note, with zero filler. Every sentence carries information.

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

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

For a one-parameter teardown tool with no output schema and annotations already covering safety, the description is nearly sufficient: purpose plus restart consequence are covered. Minor gaps remain around unsaved-state loss and behavior when no preview is running.

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

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

Schema description coverage is 0% and the single parameter flowId is never named or explained in the description. The phrase "the flow's preview" implies a flow identifier is needed, which partially compensates, but with one undocumented parameter the description leaves the argument semantics to inference.

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 (stop) plus a precise resource (the flow's preview sandbox), and it names the counterpart operation start_preview, which lets an agent separate it from flow_get_preview_status and flow_sync_preview. It stops short of explicitly contrasting with those other preview siblings, keeping it at 4 rather than 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?

No explicit when-to-use or when-not-to-use guidance; the agent must infer that this is called to tear down a preview. The cold-boot note hints at a trade-off but never states conditions, prerequisites, or alternatives such as whether a running preview is required.

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

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

Annotations only tell the agent this is a non-read-only, non-destructive, non-open-world call. The description goes much further: it discloses that the engine force-overwrites parts of package.json (dev/build/typecheck scripts and vendored command-frame + mock packages), that baseline/build deps are re-added only when undeclared so user pins survive, and that it shares a rate bucket with start_preview. This is exactly the mutation-side detail 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?

The core action and its payoff (the build gate result) are front-loaded, and every subsequent sentence adds non-redundant behavior (forced package.json fields, dep re-add rules, rate bucket). It is dense and slightly long, but no sentence is filler.

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

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

With no output schema, the description still explains the return value ('Returns the gate result'), covers the mutation side effects, the running/cold precondition, and the rate-limit interaction with a sibling. Nothing an agent needs to call this correctly is missing.

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

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

There is a single parameter (flowId) with 0% schema description coverage, and the description never mentions it or its format. It is self-evident from the name and required, so the gap is mild rather than disqualifying, but the description adds no semantic value over the bare 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 (reconcile/sync) and resource (preview sandbox vs. the flow's current files), plus the concrete downstream action (run the green-build gate: tsc + vite build). An agent can distinguish this from flow_start_preview, flow_get_preview_status and flow_write_flow_files without opening any schema.

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

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

Gives real usage context — 'the fastest way to know your code actually compiles' — and names the sibling it shares a rate bucket with (start_preview), with the explicit instruction 'sync once per change-set, not per file.' It stops short of a full when-to-use/when-not matrix against every preview sibling, but the routing guidance is clear.

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, but the description adds substantial context beyond that: exactly what is lost (stored rows on retype, row data orphaned under the old key on rename), the org-wide blast radius ('a schema change lands for every flow and station'), the blueprint constraint, and the partial-failure model ('Per-operation failures are collected rather than aborting'). This is meaningful disclosure an agent could not infer from the annotations 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?

Front-loaded with the core action, then layered with the scoping constraint, the safety rule and the failure model. Every sentence carries distinct, load-bearing information and none restates 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?

No output schema, but the description needn't explain return values; it instead covers the things that matter for a destructive mutation: scope, irreversibility, downstream dependents, and error behavior. Nothing an agent needs in order to call this safely is missing.

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

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

Schema description coverage is 60%, so the schema already documents tableName, hubToken, removeFields and the reference fields. The description maps its language onto addFields/updateFields/removeFields and reinforces that rename/retype is destructive, but adds no syntax or format detail beyond the schema. A 3 baseline 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 ('Evolve an EXISTING custom data table's schema') and enumerates the three sub-operations (add, change, drop columns). It is clearly distinguishable from sibling flow_create_custom_table and flow_list_custom_tables, which it references by name.

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

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

Gives explicit when-to-use ('EXISTING' table, identified by kebab-case name from list_custom_tables), when-not ('use sparingly' for rename/retype) and hard exclusions ('NEVER rename or reshape a table a selfPersisting blueprint reads/writes'). The alternative path (list_custom_tables) is named directly.

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, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description goes well beyond that: it clarifies the checks are deterministic/static, that the TS check proves types but never runtime behavior or device parity, that a version is stamped in the result, and which findings block deploy vs. remain advisory.

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 claim ('Deterministic STATIC checks against the platform contract') then enumerates the checks in order. The content is dense and warranted by the tool's complexity, though the single run-on sentence with nested parentheticals hurts readability.

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

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

There is no output schema, so the description must explain returns, and it does: it names flowTypeErrors, warnings, secretFindings, and the stamped .d.ts version, and explains what each means for the agent's next action. Nothing needed to interpret the result is missing.

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

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

Schema description coverage is 0% for the single required parameter flowId, and the description never mentions the parameter or what value it expects. Though flowId is inferable from the tool name, the description adds no semantic meaning beyond the obvious, so it fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('Validate a flow') and immediately enumerates the exact checks performed (guardrails, real tsc against pinned .d.ts, credential scan, whole-tree type check, advisory warnings). This is unmistakably distinct from siblings like flow_deploy_flow or flow_start_preview.

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

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

Gives explicit workflow timing ('Run it after each write batch, before start_preview') and a routing rule tied to a sibling ('secretFindings BLOCK deploy_flow; everything else is advisory'). The agent knows both when to call it and how its result gates another 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 flag destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: writes land as restorable checkpoints, are narrated in the builder chat, and carry non-obvious failure semantics (files may still have landed on error, large payloads can truncate mid-file). It also discloses the whole-file replacement model and the engine-owned path restriction.

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

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

Front-loaded with purpose and then layered with behavior; nearly every sentence carries operational value rather than filler. It is dense and fairly long, but the density is justified for a destructive write tool with tricky error semantics.

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 no output schema, the description covers everything an agent needs: mutation semantics, checkpoint/rollback behavior, engine-owned path rejection, preview-sync follow-up, validation step, error-recovery guidance, and safe file-sizing advice. Only the per-parameter docs are thin, which the schema partially covers.

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

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

Schema description coverage is only 25% (just the 'note' field), so the description is expected to compensate. It clarifies the semantics of the files payload (full contents, whole-file replacement, keep files small, engine-owned paths rejected) and indirectly explains 'note' via chat narration, but it never addresses the 'agent' or 'flowId' parameters, leaving part of the coverage gap unfilled.

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 ('Create or overwrite files in a flow's tree') and immediately scopes it ('full contents, not diffs'), which separates it from a diff/patch tool. It also names related siblings (get_scaffold, read_flow_files, validate_flow, start_preview), so an agent can place it in the workflow without opening any schema.

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

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

Gives explicit when/when-not and follow-up routing: engine-owned paths are rejected and redirected to get_scaffold, validation should happen via validate_flow before deploying, and a live preview requires a follow-up start_preview call. It even prescribes the correct recovery path (re-read with read_flow_files, never blind-retry), which is unusually actionable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered by structured data. The description usefully adds that this is an identity/context introspection call whose output includes switchable companies and unlisted-tool access, but it says nothing about auth scope, caching, or freshness of the connection 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?

It is a single sentence with no filler, which is efficient, but it is a flat list of five items with no leading verb and no front-loaded summary of purpose, making it harder to parse quickly than it needs to be. A short opening clause such as 'Returns the current connection context:' would have improved scannability at negligible cost.

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

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

There is no output schema, so the description carries the burden of explaining return contents, and it does so by enumerating the fields of interest (organisation, user, acting company, switchable companies, packs, unlisted-tool path). That is reasonably complete for a zero-parameter introspection tool, though it stops short of saying whether the packs list is filtered by permissions.

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 by the rubric this is a baseline 4. The description appropriately spends its words on what is returned rather than on inputs, which is the right allocation for a no-arg tool.

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 enumerates what the tool surfaces (caller identity, organisation/user, active company, switchable companies, allowed/listed packs, how to reach unlisted tools), which is concrete content rather than a restatement of the name. It lacks an explicit verb (e.g. 'Returns...'), so it reads as a content list, but an agent can still infer that this is a connection-context/introspection read. It does not explicitly differentiate itself from near-neighbours like list_packs or switch_company.

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 call this tool, no prerequisite or ordering advice (e.g. 'call this first to orient yourself'), and no exclusion of alternatives. The mention of 'how to reach tools that are not listed' hints at a discovery role, but that is inference, not guidance.

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

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

Annotations already establish that this writes but is non-destructive. The description adds real behavior beyond them: append semantics ('Existing notes are KEPT'), and that output is staff-facing. It doesn't cover permissions or failure modes, but for a low-risk note append this is solid added context.

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 load-bearing: purpose, append-vs-replace behavior, prerequisite source, and authoring guideline. Front-loaded with the action and 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 2-parameter append tool with 100% schema coverage, full annotations and no output schema, nothing an agent needs to invoke it correctly is missing. Return-value detail is unnecessary here.

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

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

Schema coverage is 100%, so baseline is 3. The description goes slightly beyond it by framing what the message should contain ('write what the merchant said, not your own summary'), which is genuine content-level guidance the schema's 'The note text' does not supply.

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 ('Add a note to a customer') and immediately disambiguates the mutation flavor: existing notes are KEPT, this appends. That separates it from hub_update_customer and any replace-style sibling 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?

Gives a clear precondition ('Takes the customer ID from get_customers'), routing the agent to the lookup tool first. It doesn't name an explicit when-not case (e.g., when to edit the customer record instead of annotating), but the usage context is unambiguous.

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 and destructiveHint=false, so safety is partly covered; the description reinforces and extends this with concrete behavior — appends to the end unless sortOrder overrides, and cannot drop existing choices. It adds real context beyond the annotations, though it doesn't mention 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?

Three tight sentences, front-loaded with verb+resource+scope, then the safety contrast, then the parameter nuance. Every sentence earns its place with no padding.

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

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

Covers the operation's key nuances (safe append, price format, ordering) for a write tool with no output schema. It doesn't describe the success response, a minor gap, but nothing needed to invoke correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: price is a human-readable amount ('0.70'), omitting it still prints a free choice on the receipt, and sortOrder controls append vs position. These go beyond the schema's own text.

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

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

States a specific verb and resource ('Add one choice to an existing modifier') and scopes it precisely ('leaving the rest alone'). It explicitly distinguishes itself from update_modifier, so an agent can route without opening either schema.

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

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

'This is the safe way to extend a modifier — unlike update_modifier, it cannot drop anything' names the alternative and the condition that selects this tool. The add-vs-update distinction is spelled out rather than 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?

Beyond the annotations' safety profile, it discloses non-obvious behavior: URL images are downloaded and stored server-side (so the product doesn't depend on an external site), existing photos are KEPT (additive, not destructive), and it lists format and size limits (JPEG/PNG/WebP/GIF/HEIC, 20MB each). This is genuinely valuable context not derivable from structured fields.

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

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

Dense and front-loaded, with each sentence carrying a distinct fact (source options, storage behavior, additive semantics, limits, ID source). The final sentence repeats the schema's productId note, a minor 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 mutation tool with no output schema, it covers sources, storage side effects, additive semantics, and resource constraints. It doesn't address return value/error behavior, duplicate handling, or auth/permission requirements, 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 coverage is already 100%, but the description adds meaning the schema lacks: accepted formats and the 20MB-per-image bound, plus the URL-vs-base64 selection logic. The productId guidance duplicates the schema description verbatim, which caps it below 5.

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

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

States a specific verb (add) and resource (photos/images to an existing product), and clarifies it augments rather than replaces existing photos. An agent can distinguish it from hub_upload_media or hub_update_product 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 explains the URL-vs-base64 decision rule ('base64 bytes when the merchant attached the file itself and there is no URL') and routes the agent to get_products for the ID. It stops short of naming concrete alternative tools (e.g. hub_upload_media) for the no-URL case, so it's clear context without explicit alternatives.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond by explaining that the rate is shared not copied, that later edits to the rate propagate to this group, that the rate is appended last in charging order, that merchant confirmation is required, and that past sales are not recalculated. This is exactly the side-effect context an agent needs for a destructive mutation.

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

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

Six short sentences, each carrying distinct, load-bearing information (scope, id source, sharing semantics, alternative tool, ordering, confirmation/retroactivity). The most important constraints — eligibility and side effects — are front-loaded rather than 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 destructive, non-read-only mutation with no output schema, the description covers prerequisites (existing rate, ids from get_taxes), propagation semantics, ordering behavior, and retroactivity limits. Nothing material an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so taxRateId, taxGroupId, and compounding are already documented in the input schema, establishing a baseline of 3. The description adds the useful nuance that compounding is modifiable and that ids come from get_taxes, but repeats rather than extends the schema's per-parameter definitions.

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 ('Add an EXISTING rate to a tax group') plus a secondary modification mode (changing that rate's compounding flag). The word EXISTING and the contrast with create_tax_rate make it immediately distinguishable from hub_create_tax_rate, hub_remove_tax_rate_from_group, and hub_update_tax_group.

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

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

Gives explicit routing: use create_tax_rate when the rate does not exist yet, and use update_tax_group with rateIdsInOrder to reposition an already-added rate. It also names the source of both ids (get_taxes), so an agent knows the prerequisite lookup.

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

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

Annotations already flag destructiveHint=true, but the description goes well beyond them: writes immediately, permanently recorded against the employee in stock history, no undo from here. It also discloses a non-obvious failure mode — applied: false with nothing written when stock isn't tracked — and warns against misreading that as zero stock.

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 action and the confirm-first instruction are front-loaded, and every later sentence carries distinct operational content (reason semantics, applied:false handling, the transfer alternative). It runs longer than a tight two-sentence ideal, but there is no filler to cut.

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 five-parameter destructive write with no output schema, the description covers safety, prerequisites, reason semantics, and the return-signal case (applied: false), so an agent has everything needed to call it and interpret the outcome correctly.

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

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

Schema coverage is 100%, so the enum direction mapping and quantity meaning are already documented. The description nonetheless adds decision-relevant meaning: quantity is always positive because the reason decides direction, INVENTORY_RECOUNT sets rather than adds, and picking the wrong reason misstates loss in reports. That enum-choice guidance is value beyond the schema, though the core direction mapping is duplicated.

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

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

States a precise verb+resource with scope: "Change the count of ONE variant at ONE outlet — the cabinet's 'Adjust Inventory' action." It also names the sibling it is not (create_stock_transfer) for the between-outlet case, so an agent can disambiguate without opening either schema.

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

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

Gives an explicit precondition (confirm with the merchant, repeating product/outlet/reason/number), an explicit when-not (use create_stock_transfer to move units between outlets), and a tracking prerequisite (tracking must be turned on for the product first). Routing is unambiguous.

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, but the description goes well beyond: the change takes effect on the next request with no logout, it replaces the user's entire permission set rather than merging, and it can alter the calling agent key's own permissions from the next call. It also states the failure mode (if no existing role fits, say so rather than picking the closest one).

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

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

Purpose and the confirmation rule are front-loaded, and nearly every sentence carries a distinct behavioral constraint (live effect, whole-set swap, self-impact, update_role alternative). It is on the long side for a two-parameter tool, with a bit of restatement around not acting on inferred changes, but the density is justified by the destructiveness.

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

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

For a destructive, non-open-world mutation with no output schema, the description covers what an agent needs: intent routing, mandatory human confirmation, prerequisites, blast radius on permissions, self-account risk, and the sibling to use instead. Nothing required to call it safely is missing.

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

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

Schema coverage is 100% and the schema itself already specifies that roleId comes from get_roles (not a name) and userId from get_team (not a name). The description reinforces reading get_roles first and validating that the target role carries the requested access, but adds no new identifier format or constraint beyond the schema 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 concrete verb+resource ('Move a team member onto a different role') and immediately frames the consequence ('this is how someone gains or loses access'), with merchant-phrasing examples that map real intents to the tool. It explicitly distinguishes itself from the nearest sibling by naming update_role for editing a role's permissions rather than moving a person.

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

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

Gives explicit when-to-use conditions, a mandatory confirmation protocol (name the person and role out loud), and a prohibition ('never act on a role change you inferred rather than were asked for'). It also names the alternative tool (update_role) and the prerequisite step (read get_roles first), plus the edge case of reassigning the agent's own account.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the write semantics are known. The description still adds real value beyond them: the order is left untouched, no money moves, and human confirmation is advised for paid bookings. It does not say whether the released slot is freed for rebooking or whether the cancellation is reversible.

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 action, then the boundary condition, then the operational caution. Every sentence carries distinct information; nothing is redundant with 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?

For a single-parameter destructive mutation with no output schema, the description covers the important non-structural facts: side-effect boundary (order unchanged, no money), and the human-confirmation prerequisite. Minor gaps remain around reversibility, freed-slot behavior, and required permissions.

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 (holdId) and schema description coverage is 100% ("The booking to release"), so the schema already carries the semantics. The description adds no format, sourcing, or lookup guidance for holdId, making this the standard baseline case where structured fields do the work.

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

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

States a concrete verb and resource ("Release a booked window") and, more importantly, delimits scope: it is not a refund and does not touch the order. That scope statement lets an agent separate it from sibling tools like hub_confirm_booking, hub_hold_booking, and the refund/order tools without opening any schema.

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

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

Gives an explicit when-not: money movement and refunds belong on the order, not here. It also states a precondition (confirm with the merchant before cancelling a booking somebody already paid for). It stops short of naming the exact alternative tool (e.g. hub_get_refunds / order-level refund), so routing is clear but not fully enumerated.

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 destructiveHint annotation: mandates CONFIRM FIRST, warns there is no undo, notes the order vanishes from the list rather than showing as cancelled, explains the stock-received refusal rule, and clarifies that cancelling does NOT notify the supplier. Rich operational context.

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

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

Front-loads the core action, then layers behavioral warnings in short, ordered sentences. The emphasis formatting is dense but every clause (no-undo, refusal rule, supplier non-notification) is load-bearing for a destructive irreversible operation.

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, no-output-schema mutation, the description fully covers the safety profile, the refusal edge case, and the downstream consequence. An agent has everything needed to call it correctly and advise the merchant.

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 clarifies the id is 'not a PO number'. The description's mention of 'the PO number' is about the human confirmation step, not the input parameter, so it adds little param-level meaning 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?

States a specific verb and resource ('Cancel an order') and implicitly distinguishes itself from siblings like hub_receive_purchase_order and hub_send_purchase_order by explaining cancellations relationship to receiving and sending. An agent can tell exactly what this 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?

Explicitly names the when ('an order the merchant no longer wants'), the when-not ('REFUSED once any stock has been received'), and the alternatives ('Receive the rest instead, or leave it partially received'). 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 only cover the safety profile (not read-only, not destructive), so the description carries the extra burden and does add value: it discloses the required orderId precondition, the refusal behavior when it is missing, and the effect (stops expiring, becomes receipt-findable). Idempotency and return behavior are still unstated, keeping it below 5.

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

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

Front-loaded with the core action and effect, then the requirement and rationale. The closing rationale ('a confirmed booking nobody can find on a receipt is worse than an expired hold') is colorful but does justify why orderId is mandatory, so it earns its place; slightly verbose overall.

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 2-param mutation with no output schema, the description covers purpose, precondition, and error behavior, and annotations cover the safety profile. It is nearly complete, missing only idempotency and what the confirmed result 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 coverage is 100%, so both parameters are already documented, and the description largely restates them ('the order the booking was sold on'). Baseline 3 is appropriate since the schema does the heavy lifting and the description adds little new syntax or format detail.

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

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

States a precise verb and resource plus the state transition ('turn a hold into a real booking'), which cleanly separates it from hub_hold_booking (creates the hold) and hub_cancel_booking (kills it). An agent can identify the operation without opening the schema.

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

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

Gives a clear triggering condition ('once the order behind it is paid') and a hard precondition (orderId required, refused without it). It does not explicitly name the sibling alternatives (hold/cancel) or state when to prefer them, so it stops short of 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 declare this is a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds genuine behavioral context beyond that: resources are global and reused across every service, and duplicates cause double-booking. It does not cover auth requirements or what the call returns, keeping 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?

Three sentences, front-loaded with the action, then the prerequisite, then the naming consequence. No filler and every sentence carries distinct information.

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

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

With annotations covering the safety profile and no output schema required to be explained, the description supplies purpose, precondition, and naming semantics — enough to call it correctly. A note on what the created resource returns (e.g. an id) 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 coverage is 100%, so the baseline is 3 — all three parameters are already documented. The description adds meaning beyond the schema for `name` by explaining that it is what staff see in the calendar, which clarifies naming intent rather than just echoing the schema's example.

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 — adding a single bookable entity to the company directory — and the title plus text make clear this is the booking-resource creator, not hub_create_product, hub_create_station, or hub_create_outlet. An agent can identify the correct 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?

It gives an explicit precondition — "Call get_booking_resources first" — and explains the consequence of skipping it (a duplicate splits one barber into two calendars). That is strong, actionable routing guidance. It does not state when-not to use the tool or name a sibling alternative, so it falls 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 only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds real behavioral context beyond that: the company-wide blast radius of a created set, a concrete failure mode (engine refuses availability with a 400 when neither outlet nor company has a timezone), and the interaction between bufferMinutes and overnight checkIn/checkOut windows. It omits auth/permission requirements, which is the only meaningful 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?

Four tightly packed sentences, front-loaded with the core action and the redirect to the read tool before any field-level detail. Every sentence carries non-obvious operational information; there is no filler or restated schema text.

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

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

For an 11-parameter mutation with no output schema, the description covers the highest-risk interactions (shared scope, timezone failure, buffer vs overnight). It does not say what is returned on success or how duplicate/conflicting rule sets are handled, but with no output schema declared that omission is minor.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description genuinely adds cross-parameter semantics the schema does not: weeklyHours are LOCAL wall-clock times at the outlet (with the timezone precondition), bufferMinutes consumes grid time for slots, and overnight stays should use checkInTime/checkOutTime with buffer at 0. That is additive meaning rather than restatement.

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

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

Opens with a specific verb+resource ('Create a booking policy') and immediately distinguishes itself from the sibling hub_get_booking_rules by telling the agent to call that first. An agent can tell this is the write side of the booking-rules pair without opening any schema.

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

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

Explicit when-not guidance: 'Call get_booking_rules FIRST and reuse a matching set instead — these are shared company-wide, not per product.' It names the alternative tool and the condition (shared scope) that should route the agent away from this call, which is exactly the exclusion guidance most definitions lack.

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 and destructiveHint=false, so the safety profile is covered. The description goes further by disclosing that duplicates cannot be merged (irreversibility-adjacent) and that no products are moved as a side effect, plus guidance to source the description from the merchant. It stops short of auth/permission or response-shape detail, so a 4 rather than 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?

Five tight sentences, each carrying distinct information (purpose, prerequisite, parameter branching, field-sourcing rule, exclusion+alternative). Front-loaded with the core action and 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?

With no output schema and a create tool whose annotations already state the safety profile, the description supplies everything needed to invoke it correctly: dedup prerequisite, nesting behavior, field guidance, and explicit scope boundaries. Nothing material is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description still adds semantic value beyond the schema: parentId controls subcategory vs top-level nesting, and the description field should be supplied by the merchant rather than invented. That is real meaning layered on top of the structured fields.

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

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

Opens with a specific verb+resource ('Create a product category') and immediately distinguishes itself from the update path by stating what it does NOT do (move products into the category). An agent can separate it from hub_update_category, hub_import_categories, and hub_create_product without opening any schema.

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

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

Gives an explicit prerequisite ('Call get_categories FIRST'), the reason (duplicates are easy to make and there is no merge), and a named alternative for the adjacent task ('do that with update_product and its categoryIds'). This is exactly the when-to-use / when-not / alternative structure the dimension rewards.

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 safe-create profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds a non-obvious, irreversible consequence: duplicates are unmergeable. It also stresses email fidelity to the merchant's own form. It stops short of auth/permission or rate-limit details.

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

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

Front-loaded with the action, followed by the sequencing rule and the data-integrity rule in tight, waste-free prose. Every sentence carries a distinct warning or instruction.

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-param, nested-object mutation tool with no output schema, the description covers the critical risks (duplicates, required email, not fabricating data) but says nothing about partial-address handling or what the call returns on success. Since no output schema exists, the missing return detail is a minor, acceptable 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 71%, so the schema carries most parameter meaning. The description nonetheless reinforces the one required field ('Email is required, exactly as in the cabinet's own customer form') and adds data-quality semantics for phone/address. It does not clarify the billing/shipping override relationship beyond what the schema states.

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

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

The first sentence gives a precise verb+resource combination ('Create a customer') that is unambiguous. It also references the sibling get_customers as a prerequisite, which helps positioning, though it does not explicitly contrast with hub_update_customer or hub_import_customers. Clear but not maximally differentiated from all 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 states an explicit precondition ('Call get_customers with the email or name FIRST'), explains the cost of skipping it (duplicate splits order history, no merge exists), and adds an escalation rule ('Ask the merchant for anything you do not know instead of inventing it'). This is exactly the when/when-not guidance the dimension rewards.

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

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

Annotations only provide the generic safe-write profile (readOnly=false, destructive=false). The description adds real behavioral facts annotations cannot carry: selectionType and allowQuantity are immutable after creation, allowQuantity is rejected on non-'multiple' types, and modifier names must be unique per merchant ignoring case.

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

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

The most consequential warning (the tool alone does nothing) is front-loaded, followed by the irreversible selectionType decision and then the conditional allowQuantity rule. Every sentence carries a constraint the agent cannot infer from structured fields; nothing is padding.

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

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

For a create operation with no output schema, the description covers creation semantics, the chaining requirement and immutability constraints very well, but never states what is returned (notably the new modifier id needed by link_modifier_to_category). That is a minor but real gap in an otherwise complete definition.

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 meaningfully exceeds the schema by defining each enum value with concrete examples ('single' = milk/temperature, 'multiple' = toppings, 'multiple'+allowQuantity = tick and count, 'quantity' = steppers) and by clarifying that the last two count units rather than distinct choices — information absent from the bare enum list.

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 ('Create a new question the till can ask, with its choices') and immediately distinguishes itself from hub_add_modifier_choice and hub_create_product_option by scoping to the whole modifier rather than a later-added choice. An agent knows exactly what object is being produced.

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 required follow-up ('follow it with link_modifier_to_category, or the modifier sits unused'), which is the single most important routing fact for this tool. It also implicitly routes choice-by-choice authoring to the add-choice flow via the schema note, so the agent has both when-to-use and when-not-standalone guidance.

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