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.