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

Annotations only cover the basic mutation profile (readOnly=false, destructive=false, idempotent=false). The description goes well beyond them: it discloses the permission prerequisite, that the new app is not the default, that the id is returned, the callbackUrl default-registration behavior, and the concrete failure mode NBLOCKS_NO_CALLBACK_URI when no callback exists.

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

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

Front-loads what the tool does and its return value, then layers prerequisites, side effects, and follow-up guidance in descending priority. No sentence is filler; every clause maps to a decision the agent must make.

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?

Although there is no output schema, the description states the return value (the app id). It covers permissions, default-state behavior, required callback setup, and routes the agent to get_integration_guide for the follow-on auth work, leaving no material gap for a create operation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: callbackUrl is registered as the ONLY redirect URI and default callback, that omitting it is acceptable when the port is unknown, and the downstream sign-in failure if it is missing. It also clarifies how the returned id is consumed elsewhere via the `app` parameter.

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

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

States a specific verb and resource ("Create a new Bridge app in the workspace this connection belongs to") and immediately distinguishes the result from sibling concepts by noting it does NOT become the default, pointing to use_app instead. An agent can differentiate it from list_apps, get_app, update_app and use_app 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 prescribes when to create a new app versus repurposing an existing one, and gives the reason (live users, email links, billing attached). It names alternatives (pass the id as `app`, or call use_app) and states the prerequisite that only a whole-workspace-approved connection can create apps.

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