The Bridge

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, but the description goes further: it discloses that idempotency is keyed on the feature key, that other features are preserved, that the call returns the full plan, and the exact entitlement bridge pattern the plan feature must be gated with. That is genuine added context a mutation tool 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 core action, then arguments, then the conceptual/entitlement context, then sibling routing; each block is useful, though the 'Arguments:' line partially restates the schema. Slightly long but no sentence is wasted.

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

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

With no output schema, the description supplies the return value ('Returns the full plan'), the idempotency and preservation semantics, and the integration guidance. For a 4-param mutation tool this is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conceptual linkage the schema lacks: it names the entitlement form bridge:billing.entitlement.<featureKey> and clarifies that 'name' is what customers read versus the key. It mostly echoes schema content (defaults to the key), keeping it from a 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 and resource ('Add an on/off feature to what a plan includes, or rename one it already has') and pins the scope precisely, including the dual add/rename behavior. It explicitly distinguishes the resource from siblings by defining a plan feature as an on/off entitlement versus something counted.

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 the agent: counted things belong to set_plan_quota, and removing a feature uses remove_plan_feature. It also adds a forward-looking instruction to call get_integration_guide with topic=billing before writing app code, giving clear when-to-use context beyond the tool itself.

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 (readOnly=false, idempotent=true, destructive=false), it discloses that existing URIs are never replaced wholesale, that duplicates succeed as a no-op returning added: false, and that the first URI on an app with no default callback becomes the default — a side effect not visible in 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?

The key non-destructive guarantee is front-loaded and each sentence carries information, though the trailing get_integration_guide instruction slightly lengthens an otherwise dense block.

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

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

With no output schema, the description compensates by describing return semantics (added: false) and the default-callback side effect, and it covers preconditions (absolute http(s)) and related tools, leaving nothing essential unclear.

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 meaning by stressing that only ONE URI is registered per call and by giving a local-dev example (http://localhost:5173/...) alongside the production 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 names a specific verb and resource (register ONE OAuth redirect URI on the Bridge app) and explicitly states the additive scope, distinguishing it from remove_redirect_uri and list_redirect_uris without requiring 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 explicit triggers (wiring a new environment, fixing a 'redirect_uri mismatch' error) and routes to named alternatives: get_environment_info for the current list, remove_redirect_uri to unregister, and get_integration_guide for app-side wiring.

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 it discloses real behavioral traits: DECISION_NEEDED is returned with the questions to ask when a developer decision is missing, 'anything the call does not mention is kept', and 'Returns the full plan'. The atomic 'never left half-configured' framing and the upsert-by-key rules (currency+interval, metric, key) are not derivable from the annotations. Note the tension with destructiveHint=false given the explicit remove* operations, but these are caller-named, reversible config removals rather than a true 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?

The core purpose and upsert/removal rules are front-loaded in the first few sentences, but the description then drifts into broad integration guidance (seat quotas, @RequireQuota vs browser reporting, QuotaGate) that is tangential to invoking this tool. Information-dense rather than padded, but substantially oversized for a tool definition.

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

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

For a 12-parameter mutation tool with no output schema, it covers what an agent needs: return value ('the full plan'), the DECISION_NEEDED failure mode, merge semantics for unmentioned fields, and per-collection upsert keys. Annotations cover safety/idempotency and the schema covers field detail, so nothing essential 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 itself is already rich, documenting currency rules, interval enums, quota kind/source and feature key patterns. The description adds the upsert-by-key grouping and the 'same rules as set_plan_price/set_plan_quota' cross-reference, but mostly restates what the schema already carries, so the baseline 3 applies.

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

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

The opening sentence states a specific verb and resource ('Set up or reshape ONE subscription plan in a single call') and immediately defines the upsert scope: creates on a new key, updates on an existing one. It is clearly differentiated from the many siblings that do a single piece (set_plan_price, set_plan_quota, add_plan_feature, create_plan/update_plan) by being the one-call composite.

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

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

It gives explicit when-to-use and prerequisite guidance: call list_plan_quotas without a planKey first to reuse existing metric names, and call get_integration_guide with topic=billing before writing consuming app code. It also names the CLI equivalent and routes callers to set_plan_price/set_plan_quota semantics for the nested rules.

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 annotations, it discloses consequential behavior: existing workspaces keep the plan and continue being billed, the plan disappears from the picker, checkout rejects it, and the Stripe product and prices are archived. It also states reversibility via archived: false and that the call returns the number of workspaces on the plan.

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

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

The description is front-loaded with the core behavior and then adds usage, reversal, return value, and integration guidance in a dense but purposeful sequence. Every sentence adds actionable context without repetition or filler.

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

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

For a mutation tool with annotations covering safety and no output schema, the description supplies the important missing context: what changes, what does not change, the alternative tool, the reversal path, and the return count. Nothing an agent would need before invoking it is absent.

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

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

Schema description coverage is 100%, so key and app are already documented in the schema. The description reiterates that archived: false restores a plan but adds no syntax or format detail beyond the schema's own description.

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 ('Archive a subscription plan') and details the precise effects: workspaces keep it and remain billed, it leaves the plan picker, checkout refuses it, and Stripe product/prices are archived. It also explicitly distinguishes this from delete_plan, which refuses plans that have workspaces on them.

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

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

It gives an explicit when-to-use rule ('Use it to stop selling a plan that workspaces are on') and names the alternative delete_plan and why it does not apply. It also documents the reversal path via archived: false and a prerequisite for app code consumers to call get_integration_guide with specific parameters.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds real value beyond them: clearing cancels a pending change rather than rolling back state, and it names the FLAG_NOT_FOUND failure mode. That error contract is the kind of behavioral 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?

Front-loads the core action, then semantics, error behavior, and the integration-guide pointer. Every sentence carries weight, though the closing integration-guide instruction is slightly tangential to the call itself.

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 covers the essential behaviors an agent needs: idempotency, no-rollback semantics, and the failure case. Little is missing for a simple removal operation.

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

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

Schema description coverage is 100%, so both the app and key parameters are already documented in the schema. The description only echoes 'by KEY' and adds no format or edge-case detail beyond it, making the baseline 3 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 (Remove/Clear) on a specific resource (scheduled state transition on a feature flag) scoped by KEY. It is cleanly distinguishable from set_flag_schedule, its natural opposite, and from toggle/delete 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?

Gives clear context: it is safe to call when no schedule exists, and it points to get_integration_guide before writing consuming app code. It does not explicitly name set_flag_schedule as the alternative for creating a schedule, so it stops short of full when/when-not routing.

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

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

Goes well beyond the annotations (which only state non-read-only, idempotent, non-destructive, open-world) by disclosing that keys are never echoed back, the exact semantics of connected=false and webhookConfigured=false, that payments remain disabled until setup_payments runs, and the instruction never to invent keys. This is exactly the extra behavioral 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 and the critical 'does NOT enable payments' caveat, and every sentence carries operational meaning. It is on the long side, but the density is justified rather than padded.

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 correctly explains the return shape ({ connected, webhookConfigured }) and what a false value implies, plus the pre-requisite relationship with setup_payments and get_stripe_status. Nothing an agent needs to invoke 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: the key value formats, where in the Stripe dashboard to find them, that both are required, and the instruction to ask the user rather than guess. That is genuine value beyond the schema 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 ('Store the app's Stripe API credentials') and names the downstream capability it enables (billing, checkout, subscriptions, portal). It clearly separates itself from setup_payments and get_stripe_status, which is exactly what an agent needs to choose among 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?

Explicit when-to-use and when-not: prefer setup_payments for first-time setup, use this only to rotate keys on an app where payments are already enabled, and use get_stripe_status to inspect state without writing. It also routes the agent to get_integration_guide before writing consuming code.

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 safety profile (non-read-only, non-idempotent, non-destructive, closed-world); the description goes well beyond that by disclosing the one-time plaintext return, the impossibility of re-retrieval, the handling warning (never commit the token), and that privileges default to none. These are the operationally decisive traits for a credential-issuing 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 purpose and tightly packed with the security warning, sibling routing, and prerequisite — no filler sentences. The single long paragraph with nested parentheticals is dense, though still readable and 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?

With no output schema, the description compensates by describing the return value (plaintext token, shown once) and the follow-up revoke path. Combined with 100% schema coverage, an agent has everything needed to call this correctly and safely.

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: name is the identifier used later for revocation, privileges default to none and a privilege-less token "can do very little," and expireAt omitted means no expiry. It doesn't restate the ISO 8601 example already in the schema, which keeps it additive rather than redundant.

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 API token for the Bridge app") and its scope is clearly distinct from the sibling list_api_tokens and revoke_api_token, which it names. An agent can select it 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 routes to alternatives and prerequisites: "Use revoke_api_token to destroy one" and "Before writing app code that consumes this, call get_integration_guide with topic=team and the framework the app uses." It also gives a granting policy ("grant only what the consumer needs"), so when-to-use is fully 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 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.

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

Annotations cover the safety profile (write, non-destructive, non-idempotent), and the description adds genuinely new behavior: a `warnings` result that never blocks the write, and the guidance to read and fix the flag. It does not disclose auth/permission requirements or creation side effects, but the warning semantics are real value beyond the annotations.

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

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

Purpose and prerequisite are front-loaded, but the middle is bloated with doctrine that is restated in the `rule` schema description (same privilege-vs-role example, same plan-feature guidance, same browser/backend sentence). Sentences earn their place individually but the overall block is longer than needed to select and invoke the tool.

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 tool with a nested rule object and no output schema, the description supplies the mental model, the prerequisite call, the warning behavior on the result, and the sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the 3 baseline applies, but the description goes further with argument-level meaning: key example ("beta-ui"), state three-state model, valueType defaults, on/off value typing, and rule semantics (first-match-wins, AND-ed conditions). Much of the rule detail duplicates the schema, but the conceptual framing (privilege vs role, pointing at plan feature lists not plan names) adds interpretable 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?

Opens with a specific verb+resource ("Create a new feature flag") and explicitly routes the agent away from siblings: "Use update_feature_flag to change an existing flag, and toggle_feature_flag for a quick on/off switch by key." An agent can distinguish create vs update vs toggle without inspecting 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?

States a concrete prerequisite workflow (call get_integration_guide with topic=feature-flags and the framework before writing consuming code) and names the two alternatives with the condition that selects each. It also explains the warning-handling loop after invocation, so both before/after usage is 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 only cover the generic safety profile (non-read-only, non-idempotent, non-destructive). The description adds behavior the agent could not infer: the DECISION_NEEDED no-op path when developer decisions are missing, the 'returns the full plan' outcome, and the quota-counting contract (backend decorator vs browser reporting, never both). That is substantive disclosure beyond 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?

Core purpose and alternatives are front-loaded effectively, but the trailing paragraphs on quota counting and the integration guide are lengthy and only loosely tied to invoking create_plan. They add useful ecosystem context but dilute the tool's own call 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 9-parameter creation tool with no output schema, the description supplies the missing return statement ('Returns the full plan'), the failure mode (DECISION_NEEDED), and the correct follow-up calls. Nothing an agent needs to invoke this correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning on top: why key must be stable and that flag rules point at features not the key, that amount 0 is legitimate (free/contact-sales), and the conditional dependency currency/trial are only needed when amount is above 0, which the schema does not express as a rule.

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 scope ('Create a new subscription plan with its first recurring price'), immediately distinguishing it from siblings like set_plan_price and apply_plan. An agent can tell exactly what state this call leaves behind 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 to alternatives and conditions: add prices via set_plan_price, quotas via set_plan_quota, all-in-one via apply_plan, later edits via update_plan, and pre-work via get_integration_guide. It also states when the tool refuses (missing price/currency/trial decisions), which is real 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 declare the safety profile (not read-only, not idempotent, not destructive, closed-world), and the description adds genuinely new behavioral facts: the key is permanent, matching compares the whole key exactly ('REPORTS_VIEW' does not match REPORTS_VIEW_ALL), and the privilege starts ungranted. It does not cover permissions or rollback, but adds meaningful state-consequence 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-loaded with the definition of the resource, followed by argument notes and workflow guidance; every sentence carries information. It is a little sprawling at six sentences, with policy advice mixed into a tool description, but nothing is gratuitous.

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

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

For a three-parameter creation tool with no output schema, the description covers creation semantics, the ungranted default state, the follow-up calls needed to actually grant it, and a pointer to the integration guide. 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%, so the schema already documents all three parameters, and the baseline is 3. The description adds only marginal value beyond it (key permanence, exact-match comparison), largely restating the schema's example and casing rule.

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 and defines what a privilege is ('a named permission roles can grant'), which distinguishes it from create_role, update_privilege and delete_privilege without opening any schema. An agent knows exactly what this call produces.

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

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

Explicitly routes the agent: a new privilege is granted by no role until added via update_role (with the full privilege list) or create_role, and it directs consumers to get_integration_guide with topic=team before writing app code. It also states the preferred access-control pattern (flag rule on a privilege) versus the anti-pattern (hard-coded role check).

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, so safety is covered. The description adds real behavioral context: what isDefault actually does, that privilege keys are matched whole (REPORTS_VIEW != REPORTS_VIEW_ALL), and that role capabilities are only defaults until read back. It omits what happens on a duplicate key or invalid privilege, which keeps it from a 5.

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

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

Purpose is correctly front-loaded, but the middle drags in integration-architecture advice (flag rules, never hard-coding role checks in app code) that is only tangential to invoking this tool. The parameter listing is a single dense sentence and the piece is longer than the operation warrants.

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

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

For a 6-parameter mutation tool with no output schema and full schema coverage, the description covers purpose, routing, parameter intent, and downstream integration needs. Only failure modes (duplicate key, unknown privilege) are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description still adds value: it characterizes privileges as KEYS and points to list_roles for the valid set, restates key as a stable code reference, and clarifies isDefault's default. It does not add syntax beyond the schema, so not a 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?

Opens with a specific verb+resource ("Create a new access role") and immediately separates itself from update_role and set_default_role, so an agent can route correctly without opening a schema. The scope is unambiguous.

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

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

Explicitly names the alternatives and the condition that selects them: use update_role for an existing role, set_default_role to promote an existing one. It also routes the agent to list_roles for privilege keys and get_integration_guide before writing consuming code.

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 (readOnly=false, destructive=false, idempotent=false); the description adds a real behavioral fact those do not encode — the owner user is created and invited as a side effect of this call. It does not say what happens on a duplicate/invalid owner email or what is returned, so 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?

Front-loaded purpose sentence followed by a compact argument list and two follow-up pointers; all sentences carry information. It is slightly list-heavy, but nothing is wasted.

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

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

For a non-idempotent creation tool with no output schema, the description covers the resource, the required owner, the side effect of owner creation, and the next-step tooling. It stops short of describing what the call returns or how duplicate tenants are handled.

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 does add genuine meaning for 'plan' (it is the KEY compared by feature-flag rules, not the display name) and for locale, but it omits the 'app' parameter entirely, so the net gain over the schema is modest.

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 tenant') and immediately disambiguates the term as 'workspace/customer account' in the Bridge app, which separates it from create_app, create_user, and create_plan in the sibling list.

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

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

Gives concrete forward guidance: 'Use invite_user to add more users to the tenant afterwards' and 'Before writing app code that consumes this, call get_integration_guide with topic=team'. It lacks any explicit when-not-to-use or sibling-selection condition (e.g. create_test_user vs. this), so it stops short of a 5.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it discloses that no plan is attached, no emails are sent, test sign-ins never count as real ones, and that the call is refused on production/live Stripe unless confirm repeats the exact app name. This is rich, non-obvious 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?

Purpose and return values are front-loaded, and each sentence adds distinct value (return payload, test-fixture semantics, production guard, CLI equivalence, auth-guide routing). It runs long at five sentences, but none is disposable filler, so the length is largely earned.

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

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

Given no output schema, the description supplies the return values (email and generated password) and their downstream use. It covers the mutation's side effects, the refusal guard, and follow-up calls, leaving nothing an agent needs in order to invoke it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented. The description nonetheless adds meaning: it explains the confirm-trigger condition (production or live Stripe keys) and that confirm is the app's exact name repeated only after user agreement, reinforcing the schema's 'do not supply on your own initiative' note.

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

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

States a specific verb (create) and resource (test user) with exact scope: a generated email/password, its own '[test] …' workspace, marked as a test fixture. This is clearly distinguishable from siblings like invite_user, create_tenant, and get_user, which create or fetch real users/workspaces.

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 to alternatives: 'pass them to verify_login' after creation, and 'Before writing app code that signs users in, call get_integration_guide with topic=auth.' It also names the refusal condition on production/live-Stripe and instructs the agent to ask the user first, covering when-not-to-invoke without prompt.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description's job is to add context — and it does: newest-first ordering, the enumerated reason codes, the fact that reasons are admin-only while the end user is told only that credentials were wrong, and the auto-generated plain explanation and fix per failure. That last point materially changes how an agent should present the output.

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 trigger, then return shape, then the admin-only caveat, then the sibling pointer — a sensible order with no filler sentences. The middle enumeration of reason codes is long but functional, since those tokens are what the agent will relay.

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 carry the return contract, and it does: attempts, ordering, per-failure reason code plus explanation and fix, and three user-state flags. With all four parameters documented in the 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 description coverage is 100%, so app, user, limit and since are already documented with defaults and bounds in the schema. The description adds no parameter-level detail (e.g. no mention of the since window or the 100 cap), so the baseline 3 applies.

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

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

States a specific verb and resource (debug sign-in) and enumerates the exact payload: recent sign-in attempts, newest first, each with failure reason, explanation and fix, plus user existence/password/workspace facts. It is unmistakably distinct from list_users or get_user, which would be the other way to reach this data.

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 trigger is explicit and front-loaded: 'When someone cannot sign in.' It also routes the agent to the alternative verb by name and condition — 'To reproduce a sign-in yourself, use verify_login' — versus the diagnostic use here. No explicit when-not-to-use case is given, which is the only gap.

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/readOnlyHint/idempotentHint, but the description adds the details an agent actually needs: exactly what is destroyed (rule, schedule, evaluation history), the silent fallback to hard-coded defaults, no undo/no archive, the confirmation contract, and the FLAG_NOT_FOUND failure mode.

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 irreversibility warning, which is the right priority for a destructive tool, and every sentence carries actionable content. It runs long and packs multiple concerns (fallback behavior, integration guide pointer, error code) into one block, so it is dense but slightly over-full.

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

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

For a destructive, no-output-schema tool, the description covers consequences, reversibility, confirmation semantics, dry-run preview, and failure modes — everything an agent needs to call it safely and correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: confirm must equal the exact key and must only be supplied after explicit user request (not agent initiative), and dryRun previews without needing confirm. The added constraint on confirm goes beyond the schema text, though per-parameter coverage is otherwise complete.

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

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

Opens with a precise verb+resource+scope: 'Permanently delete a feature flag by its KEY.' It clearly distinguishes this from siblings (toggle_feature_flag, update_feature_flag, clear_flag_schedule) by naming the alternative that most callers actually want.

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 and when-to-prefer-an-alternative: 'Prefer toggle_feature_flag to switch a flag off, which is reversible.' It also prescribes the correct retire sequence (remove consuming code first, then delete) and positions dryRun:true as the required first step.

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 (destructiveHint=true, idempotentHint=false): it names what is archived (Stripe product and prices), the exact refusal error and that nothing mutates in that case, the required confirmation flow with the 'never supply it on your own initiative' guardrail, the dryRun preview semantics, and the PLAN_NOT_FOUND failure mode.

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, refusal behavior, and the confirmation gate; every clause carries operational weight. It is long and uses shouted emphasis (NO, REFUSED, REQUIRES CONFIRMATION), but no sentence is filler, so the length is justified for a destructive 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 4-parameter destructive tool with no output schema, the description covers the mutation's side effects, the refusal branch, the two-step confirmation workflow, error codes, and a pointer to get_integration_guide for downstream app code. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3; the description earns one more by supplying the call-ordering semantics (dryRun first, then re-call with confirm set to the exact key) that the schema fields describe only individually. Much of the confirm/dryRun text overlaps the schema descriptions, so it is additive rather than fully novel.

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 (delete a subscription plan) and immediately scopes it: only plans NO workspace is on, with the side effect (Stripe product/prices archived). It distinguishes itself from the nearest siblings by naming archive_plan, set_tenant_plan, and delete_tenant as the alternatives in the refusal path.

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 and when-not-to-use: a plan in use is REFUSED with PLAN_IN_USE and nothing changes, and the agent is told exactly which sibling to pick for each user choice (archive_plan, set_tenant_plan, delete_tenant). It also states the required sequence (dryRun first, then confirm) and the prerequisite guide 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 and readOnlyHint=false, but the description goes well beyond them: it explains what is destroyed (the privilege removed from every role, holders lose it at next sign-in, flag rules and app code stop matching), the hard constraint (AUTHENTICATED cannot be deleted), the confirm/idempotency safety contract, and the PRIVILEGE_NOT_FOUND failure mode.

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, irreversibility, and confirm contract are front-loaded well, but the tail drifts into tangential platform guidance about flag rules, hard-coded role checks, and privilege-rule key matching ('REPORTS_VIEW' does not match REPORTS_VIEW_ALL). That material is relevant to the auth model but not to invoking this delete tool, so it dilutes an otherwise tight definition.

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 covers effects, permissions needed, error conditions, the reversible preview path, and sibling routing — everything an agent needs to call this destructive tool safely.

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 adds meaning by clarifying that confirm must be the exact resource key and must not be guessed or copied from a fuzzy match, and that dryRun needs no confirm. It stops short of documenting the app parameter's scoping behavior in prose, so it exceeds but does not maximize the dimension.

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

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

States a specific verb and resource ('Permanently delete a privilege') plus the addressing mode (its key, or id, from list_privileges). An agent can immediately distinguish this from create_privilege, update_privilege, and delete_role 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 and an alternative: 'To take a privilege away from one role only, use update_role instead.' It also prescribes the ordering (dryRun first, then confirm only after explicit user request) and the correct remediation path (get_integration_guide with topic=team) for consuming code, leaving little 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 destructiveHint=true, but the description adds critical non-obvious behavior: irreversibility, that holders are NOT migrated, that flag rules and app code checking the key silently stop matching, the confirm gating requirement, and the ROLE_NOT_FOUND failure mode.

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 destructive warning and confirm requirement are front-loaded, which is correct. The trailing guidance on privilege-rule matching, app-code patterns, and get_integration_guide is tangentially related to a delete operation and adds length, though it is well-disclosed.

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, five optional params, and a high-risk mutation, the description supplies everything needed: side effects, prerequisites, confirmation protocol, dry-run behavior, and error semantics. An agent can call this correctly without further context.

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 semantic nuance beyond the schema — that confirm must reflect an explicit user request rather than agent initiative, and that dryRun needs no confirm. It does not add much on id/key/app beyond what the schema states.

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

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

States a specific verb and resource (permanently delete an access role) and clarifies the addressing mode (key or id from list_roles). It is immediately distinguishable from siblings like create_role, update_role, delete_privilege, and list_roles.

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 covers when-not (default and OWNER roles cannot be deleted; make another default with set_default_role first), prerequisite work (reassign holders with update_user), and the recommended dryRun-first workflow. Alternatives and preconditions are named, not implied.

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 idempotentHint=false, but the description adds substantial behavioral context beyond them: irreversibility, the mandatory two-step confirmation protocol, the specific failure modes (TENANT_NOT_FOUND, TENANT_AMBIGUOUS, confirm mismatch) that all leave data intact, and that dryRun requires the same privilege as the deletion. This is exactly the extra context a destructive tool 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?

The description is long but front-loaded, leading with the destructive scope and irreversibility, then the confirmation ritual, then failure modes, then dryRun, then the sibling alternative. Each sentence carries operational weight; the trailing get_integration_guide pointer is the only mildly tangential element, keeping it just under a 5.

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 with no output schema, the description covers everything an agent needs: the confirmation protocol, dryRun preview semantics, all named error outcomes, the sibling alternative, and even a follow-up tool for app integration. No return-format gap because there is no output schema to describe.

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 real meaning: confirm must be 'the exact tenant name' (clarifying the schema's generic 'repeat the exact key'), the confirm/dryRun interaction, and that name resolution happens before confirmation. It stops short of explaining the app param, but the parameter-level workflow semantics go beyond the schema 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?

Opens with a specific verb+resource plus the blast radius ('Delete a tenant and everything scoped to it (its users, subscription and data)'), so the agent immediately knows the scope of destruction. It explicitly distinguishes itself from the sibling remove_user ('To remove a single person instead of the whole workspace use remove_user'), which no other sibling needs to be consulted to disambiguate.

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

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

Gives an explicit when-to-use sequence: resolve the tenant first, then call again with confirm set to the exact tenant name, and only after the user has explicitly agreed. It also sets a clear exclusion ('never supply the confirmation on your own initiative') and points to dryRun as the safe precursor, so the agent knows both the trigger and the guardrail.

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/idempotent/non-destructive, and the description adds genuinely new behavioral constraints: the strict secret-handling rule (send '<set>' for BRIDGE_API_KEY or any *_KEY / *_SECRET, never the real value, since only presence and placement are checked) and the fact that it compares against the live app rather than static config. This is exactly the kind of 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-loads the purpose in the first clause and keeps every sentence load-bearing, including the enumerated failure modes that justify the tool's breadth. The dense middle paragraph is long, but the detail is functional rather than padding.

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

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

With no output schema, the description still specifies the return shape ('every concrete difference with its fix'), the input contract, and the remediation path via sibling tools. An agent has everything needed to call it correctly and act on 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it scopes `env` to Bridge-related variables only and states the placeholder convention for secrets, and it explains that `framework` is inferred when omitted. The `app` parameter's 'omit to use current app' semantics live mostly in the schema, so this stops short of 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 and resource ('Check a project's Bridge configuration against the real app') and then enumerates exactly what it detects (wrong app id, base URL pointing at another environment, unregistered callback URL, disallowed origin, missing variable, secret in browser-bundled var, signing-key availability). This makes it trivially distinguishable from siblings like get_environment_info or debug_auth_issue.

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

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

Explicitly says what to pass ('only the Bridge-related variables from the project's .env files'), names the CLI equivalent (`bridge diagnose` reads .env itself), and routes follow-up work: get_environment_info for expected values, add_redirect_uri and update_app for fixes. When-to-use and alternatives are both 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?

Goes well beyond the annotations: 'Nothing is written and no eval is recorded,' the evaluator is the same one the server/SDKs use so results match production, and it discloses the rolloutPct<100-without-identity fallback to otherwiseValue plus the `warnings` behavior for misleading settings. None of this is derivable from readOnlyHint/idempotentHint.

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 write-safety guarantee, then parameters, then the rolloutPct caveat. It is on the long side and somewhat dense, but nearly every clause carries non-redundant information, so little could be cut without losing behavioral detail.

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

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

With no output schema, the description still describes the return shape (resolved value, which branch matched, whether a bucket applied, the bucket number, and warnings), and covers the identity-required edge case. An agent has everything needed to call it correctly.

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

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

Schema coverage is already 100%, yet the description adds real meaning: identity is the id the rule buckets on (user/tenant/device), attributes is a flat map with a worked example, dotted paths and nested objects both resolve, and roles are referenced by their KEYS. It also flags the identity-required precondition for partial rollouts.

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+scope: 'Dry-run a feature flag against a synthetic context.' It explicitly routes away from siblings, noting get_flag shows the rule and update_feature_flag changes it, so an agent can distinguish it 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?

States the concrete use case ('check targeting you just wrote before shipping code that depends on it') and contrasts the read-only dry-run against get_flag (inspect) and update_feature_flag (mutate). When-to-use is explicit and the alternatives 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 declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavioral context — deterministic key ordering, exclusion of environment-specific data (no ids, no eval counters), and CLI-format compatibility. It does not discuss permissions or rate limits, but for a read-only export those are marginal, so 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-loads the core action and the bundle shape in the first sentence, then spends the remaining sentences on portability guarantees and the sibling alternative. The field enumeration is dense but each clause carries decision-relevant information; only minor trimming 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?

There is no output schema, so the description carries the return-value burden — and it does, specifying the envelope ({version, flags}), ordering, and per-entry fields, plus what is deliberately omitted. An agent has everything needed to call it 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 100% and the single `app` parameter is fully documented in-schema (including the 'omit to use current app' fallback). The description adds nothing about the parameter, so the baseline 3 applies — the schema does all the work here.

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 (export) and resource (feature flags) plus the exact artifact produced — a portable 'flags as code' bundle. It distinguishes itself from both import_feature_flags (the counterpart) and list_feature_flags (the id-preserving reader), so an agent can pick it without opening another schema.

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

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

Explicitly names the alternative and the selecting condition: 'Use list_feature_flags instead when you just want to read the current setup, since that keeps the ids.' It also frames import_feature_flags as the round-trip partner, giving the agent a clear when/when-not boundary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the breadth of the read (full app configuration, not a slice) and positioning it as the diagnostic entry point, though it says nothing about response size or auth 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 sentences, each earning its place: scope first, then usage priority plus alternatives, then the mutation counterpart. No filler and the most decision-relevant content is front-loaded.

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

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

With no output schema, the description compensates by enumerating what the read returns, and it routes the agent to siblings for narrower slices. For a single-optional-param read tool this is complete enough to invoke correctly without further exploration.

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 optional parameter ('app') exists and schema description coverage is 100%, so the schema already explains the id and the omit-to-use-current-default behavior. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Read the full Bridge app configuration') and enumerates the concrete contents (name, URLs, login methods, redirect URIs, default role, plan/billing setup). It also explicitly separates itself from the narrower readers get_auth_config, get_environment_info, and get_setup_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?

'Call this first ... before changing anything or diagnosing auth issues' gives an explicit trigger condition, and the description names three narrower alternatives with the condition that selects each. The write counterpart, update_app, is also named, closing the read/write loop.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds substance beyond that: it lists the concrete config surface (magic link, passkeys, MFA, each social provider, access/refresh TTLs) and the nuance that password is always available on Bridge. It does not state auth/permission requirements, 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?

Front-loaded with the primary purpose and kept to a few sentences, each earning its place by adding scope, usage, or sibling routing. The parenthetical enumeration of five social providers is slightly verbose but genuinely informative 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?

No output schema exists, so the description correctly compensates by enumerating the returned configuration surface. Combined with usage context, alternatives, and sibling disambiguation, an agent has everything needed to select and call this tool 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 `app` parameter and schema description coverage is 100%, so the schema already documents it fully ('Omit to use the current app'). The description adds no parameter-level detail, which is the expected baseline when the schema carries the load.

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

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

Opens with a specific verb+resource ('Read the Bridge app's login/auth configuration') and enumerates exactly what is returned: enabled login methods and token TTLs. It actively differentiates from siblings by naming get_app as the broader alternative and get_environment_info as the redirect/env-var 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?

Gives explicit when-to-use scenarios ('building or debugging login UI/flows — deciding which login buttons to render or why a provider button is missing') and routes to two named alternatives with the conditions that select them. 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=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: it explains what customCss means (whether a stylesheet is uploaded) and that defaultValues lets you distinguish customized from default settings, which is real behavioral insight. It stops short of covering permissions or error behavior, 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?

Two sentences, front-loaded with purpose and then the read-before-write rationale. The long field enumeration is not padding — with no output schema it is the only place the return shape is documented, so every item 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?

With no output schema, the description fully carries the return-value burden by listing the applied color/font values, customCss and defaultValues. Combined with annotations covering the safety profile and a 100%-documented single optional param, 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 (app) and schema description coverage is 100%, so the schema already explains its meaning and the 'omit to use the current app' default. The description adds nothing about the parameter, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Read the current branding of the Bridge-hosted auth pages') and scopes it precisely to login/signup/reset password pages, which distinguishes it from the broader app/auth config siblings. It also enumerates the returned fields so the agent knows exactly what this read yields.

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

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

Explicitly instructs 'Read this before calling update_branding so you keep the values you are not changing,' naming the sibling tool and the condition that selects it. The read-before-write workflow 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: which env-var names each framework reads (VITE_BRIDGE_*, NEXT_PUBLIC_BRIDGE_APP_ID, BRIDGE_APP_ID/BRIDGE_API_KEY), that bridge-angular has no env-var convention, and that the base URL reflects the server's own environment.

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 opening sentence front-loads the return contents and the usage sentence follows immediately. The framework-specific env-var enumeration is long but each clause conveys distinct, actionable information; only minor trimming would be 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?

With no output schema, the description carries the burden of explaining return values and does so thoroughly by enumerating each returned field, including per-framework env-var names. 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?

There is a single optional parameter with 100% schema coverage, and the schema already explains it ('Omit to use the current app'). The description does not add syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Read) and enumerates exactly what it returns — app id, API base URL, redirect URIs, callback URI, CORS origins, env-var names — and explicitly differentiates itself from siblings get_auth_config and get_app. An agent can identify this tool 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-to-use triggers (scaffolding a project, writing a .env, debugging a redirect/CORS mismatch) and routes to alternatives with their distinct purposes: get_auth_config for login-method setup, get_app for the full app object. 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: the FLAG_NOT_FOUND failure mode, the absence of evaluation counts through the API, and the semantics of the `warnings` array including the fact that warnings do not block a write. That is genuinely useful non-structural 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-loaded with the core action and key semantics, then failure/warning behavior. The long field enumeration in the first sentence is slightly list-heavy, but every clause carries information an agent needs, so there is little waste.

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

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

With no output schema, the description correctly documents the return payload, the error code on a missing key, and the non-blocking warning behavior. An agent has everything required to call it and interpret results without further sources.

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

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

Schema description coverage is 100%, so both `app` and `key` are already documented in the schema, including the same "beta-ui" example. The description reinforces that lookup is by KEY but adds no syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb and resource ("Read one feature flag by its KEY") and enumerates exactly what is returned (id, key, state, valueType, onValue/offValue, rule, schedule, source). It explicitly distinguishes itself from list_feature_flags, so an agent can tell the two apart 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?

States the when: "Use this to confirm a flag key and its targeting before relying on it in code." It also names the alternative and its scope ("list_feature_flags shows every flag"), giving a clear selection rule between the two siblings.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: it returns markdown plus a source URL, the server cannot detect the framework, master topics ignore the framework and orchestrate routing to per-framework guides, and 'guidance is a default, not a mandate'. This is unusually rich disclosure for a read-only 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 purpose and usage, which is good, but the topic catalogue is restated almost verbatim in both the description and the schema enum descriptions, and the paragraph runs long with heavy parenthetical chaining. Information-dense but not efficiently sized.

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?

Complete for a read-only guide lookup: no output schema exists, and the description still discloses the return format (markdown + source URL), the topic taxonomy, the framework requirement rules, and cross-topic sequencing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the enum list does not: the master-vs-per-framework distinction (framework REQUIRED vs IGNORED), the orchestration role of master/flags-master/billing-master, and the 'pass the one the target app actually uses; this server cannot detect it' constraint on framework.

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 the Bridge integration guide for a topic') and immediately frames its scope as the opinionated consumption path, which distinguishes it from siblings like diagnose_integration or scaffold_flags_integration. An agent can tell what it returns and why it exists 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 prescribes when to call it ('BEFORE writing or changing app code that reads a feature flag, renders billing or team UI, or wires authentication') and warns against the alternative (hand-rolling against SDK internals). Adds sequencing rules ('Start at topic=master when integrating for the first time', 'read topic=fit-together before setting up flags/roles/plans/limits').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds meaningful behavioral context beyond that: it enumerates the returned fields and discloses the specific error condition (PLAN_NOT_FOUND). It stops short of mentioning permissions or rate limits, so it is useful but not exhaustive.

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

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

The description is front-loaded with purpose and immediately follows with return shape, alternatives, and error behavior. Every sentence earns its place by adding distinct value: lookup scope, return contents, sibling routing, and failure mode. There is no filler or repetition.

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

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

Given there is no output schema, the description appropriately describes the return fields in detail (key, name, prices, quotas, etc.). Combined with the explicit sibling alternatives and error condition, an agent has enough context to invoke this read tool correctly. The 100% schema coverage for parameters and the read-only annotations mean nothing essential 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 both parameters are already documented in the schema, including the example 'pro' for key and the app fallback behavior. The description restates the key example but adds no new syntactic or semantic detail beyond what the schema provides. A score of 3 is the correct baseline when the schema does the heavy lifting.

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

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

The description opens with a precise verb and resource: 'Read one subscription plan by its KEY'. It states the exact lookup scope and what is included (prices and per-metric usage quotas), which distinguishes it from list_plans and get_stripe_status. An agent can identify the operation and its target 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 names specific alternatives and the conditions that select them: list_plans to discover keys, list_plan_quotas when only the quota array is needed, and get_stripe_status to verify billing wiring. The failure condition PLAN_NOT_FOUND further clarifies behavior. This is explicit when-to-use guidance with no guesswork.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing the exact return fields and the ROLE_NOT_FOUND failure mode, though it omits whether the lookup is app-scoped in effect.

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 with zero filler: identity, usage routing, and failure mode in that order. The key constraint is front-loaded and 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?

There is no output schema, so the description compensates by enumerating the returned fields (key, name, description, isDefault, privileges) and the error case. For a two-parameter read tool, an agent has everything needed to call it 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 coverage is 100%, so both the app and key parameters are already documented in the schema, including the "ADMIN"-style example. The description reinforces the key semantics but adds no format or case-sensitivity detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ("Read one access role by its KEY") plus the scope of what is returned. It explicitly contrasts itself with list_roles, so an agent can distinguish it from the sibling 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?

Provides an explicit use case ("confirm a role key and its privilege keys before gating a route or component on them") and names the alternative (list_roles) for enumerating all roles. Both the when and the alternative are stated, not implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, and the description correctly reinforces 'changes nothing.' Beyond that it discloses non-obvious behavior: the tool list is a snapshot that may be stale, and the `bridge-catalogue:` line in results is the surest staleness signal. It does not cover error modes or exact return field names, but the added context is meaningful.

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

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

Front-loaded with purpose, then staleness detection, then the no-side-effects note, then sibling routing. Dense and mostly waste-free, though the closing alternatives sentence and the toolCount explanation overlap slightly in emphasis.

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 return-value burden and does so at a high level (version, toolCount, the catalogue line). For a trivial zero-side-effect introspection tool this is sufficient; only the exact response shape and the handling of the optional `app` argument remain 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%, so the optional `app` parameter is fully documented by the schema; the baseline is 3. The description adds nothing about `app` semantics — and its claim 'Takes no arguments' is inaccurate given the optional app parameter, which mildly undercuts rather than helps.

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: report the Bridge MCP server version and exposed tool count. It explicitly distinguishes itself from siblings by naming get_started (what Bridge does) and list_apps (which app the connection acts on), 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?

Gives a concrete when-to-use condition (diagnosing a stale tool list) and states the remedy (tell the user to reconnect) rather than concluding a capability is missing. It also names two alternative tools for adjacent questions, which is exactly the routing guidance 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 cover the safety profile (readOnly, idempotent, non-destructive, not open-world), yet the description adds real behavioral context: the three possible statuses per item ('configured, missing or attention'), the next-step field, the separate `productionNeeds` set, and the non-obvious rule that test-user sign-ins never count as the first real one. That last caveat is genuine behavior an agent could not 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?

Front-loaded with the core purpose, then the item list, then the caveat, then the alternative route — a logical order with no filler sentences. The parenthetical enumeration of checklist items is dense but each element earns its place by telling the agent what to expect in the result.

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 return-shape burden and does so: per-item status values, per-item next steps, and a `productionNeeds` block. Combined with a single well-documented parameter and full annotation coverage, nothing an agent needs to call or interpret this tool 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?

Only one optional parameter with 100% schema description coverage, so the schema already documents `app` and the omit-for-current-app default. The description says 'this app' but adds no format, id-source, or override detail beyond the schema. Baseline 3 is appropriate when the schema carries the 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+resource (readiness checklist for this app) and enumerates exactly what it covers: redirect URIs, default callback, allowed origins, UI URL, sign-in methods/SSO, email sender, Stripe, plans, first real sign-in. This is clearly distinguishable from siblings like get_started, get_auth_config, get_stripe_status or get_app.

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 routing decision for one case: 'To prove sign-in works, create_test_user then verify_login' — telling the agent when a different path is correct. It also notes the CLI equivalence ('Same as `bridge setup status`'). It does not state exclusions against adjacent diagnostics tools (diagnose_integration, debug_auth_issue, get_started), so it stops short of a full when/when-not map.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description reinforces it with 'takes no arguments and changes nothing.' It adds real value by exposing the resource URI pattern bridge://guides/decisions/<area>, which is not derivable from annotations or the empty schema.

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

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

Front-loaded with 'Start here.' and every clause carries routing or content information. The single long em-dash sentence is dense and slightly run-on, and the get_integration_guide cross-reference appears twice, costing a little efficiency.

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 parameters, no output schema and annotations covering safety, the description fully specifies the return content (the map, per-area question, decision guide path) and the follow-up calls. Nothing an agent needs in order to call and act on 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?

Zero parameters, so the baseline is 4; the description sensibly confirms 'takes no arguments' rather than leaving the agent to infer it. No further parameter meaning is possible or needed.

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 exactly what the tool returns — an orientation map of Bridge's areas (login, teams, roles, payments, feature control, branding, go-live) with the follow-up question and decision guide for each. It explicitly distinguishes itself from get_integration_guide (same content as topic=orientation) and routes the agent onward to get_app and get_setup_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 three concrete triggers — new to Bridge, developer asks what Bridge can do, or before choosing a setup path — and adds a sequencing rule ('Then read the app as it is today with get_app and get_setup_status'). It also names the correct alternative (get_integration_guide topic=fit-together) before setting up flags, roles, plans or limits.

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, idempotent, non-destructive), and the description goes well beyond it: it defines what connected=true implies for checkout/subscriptions/billing portal, explains that webhook failures do NOT block checkout but break event sync, clarifies that a single rejection is not a problem versus a sustained streak, and guarantees no key or secret is returned.

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

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

Front-loaded with the core purpose, then the return shape, then failure semantics and repair path. It is long, but with no output schema the field enumeration earns its place; the dense parenthetical about rejection timing is the only slightly hard-to-parse stretch.

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 fully by enumerating every returned field and interpreting the key ones (webhookConfigured, setupStatus, webhookRejectionsSustained). Failure interpretation and the remediation path are both present, so nothing an agent needs to 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 100% and the single optional 'app' parameter is already documented there (including the list_apps pointer and the omit-to-use-current behavior). The description adds no further parameter syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Check whether Stripe is connected to the Bridge app and whether its Stripe webhook works') and distinguishes itself from setup_payments and list_plans by name. An agent can route correctly 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 says when to call it ('Call this before assuming billing works'), what to do when connected is false ('use setup_payments to supply the keys'), how to repair a broken webhook, and which sibling to use for plans/prices ('For the plans and prices themselves use list_plans'). When, when-not, and alternatives are all 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description goes beyond them by disclosing the resolution order for 'name' and two concrete failure modes (TENANT_NOT_FOUND, TENANT_AMBIGUOUS) — genuinely useful behavior that annotations cannot convey. It doesn't mention auth scope, 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?

Two sentences, no filler, with the lookup key and its fallback front-loaded before the return contents and error conditions. Every clause 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?

There is no output schema, and the description compensates by enumerating the returned fields (plan, locale, logo, mfa, payment status, trial, onboarded, owner, metadata) plus the two error outcomes. For a two-parameter read tool with rich annotations, 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 the baseline is 3. The description's extra detail is the precise fallback rule (id only used when the name matches nothing), which sharpens but largely restates the schema's own note; 'app' is not discussed in the description at all.

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

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

States a specific verb and resource ('Get one tenant') and pins down the lookup key (NAME, with id as fallback), which immediately distinguishes it from the sibling list_tenants and update_tenant. An agent can tell what it retrieves 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?

Tells the agent where the required identifier comes from ('as shown by list_tenants') and gives an explicit fallback condition (id accepted when the name matches nothing). It stops short of stating when to prefer this over list_tenants or other single-record getters, so it's clear context rather than full 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 already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral detail: the shape of the returned record (role, enabled, onboarded, teams, custom params, tenant) and two named failure modes (USER_NOT_FOUND, USER_AMBIGUOUS), including the ambiguity condition.

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 argument sourcing, return contents, and error semantics in tight sequence. No filler sentences and every clause carries information.

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

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

With no output schema, the description compensates by naming the returned fields, and it covers the two realistic failure paths. The optional `app` parameter is documented in the schema, so nothing needed to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the id-as-fallback for tenantName. The description restates the two required parameters without adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a precise verb+resource+key ("Get one user of a tenant by EMAIL"), which unambiguously separates it from list_users, get_tenant, and update_user. The scope (single user, scoped to a tenant, keyed by email) is fully specified in the first sentence.

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 explains where each required argument comes from ("tenantName ... from list_tenants", "email ... as shown by list_users"), which effectively routes the agent through prerequisite list calls. It stops short of stating when to prefer this over alternatives or any exclusions, so it is clear context rather than full 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?

Goes well beyond the annotations (which only declare idempotent/non-destructive/non-readonly) by disclosing atomic pre-write validation, that a bad rule fails the whole import rather than half-applying, that the tool NEVER deletes and instead reports extraneous flags, and what dryRun actually returns (created/updated/left-alone plus field diffs). It does not state auth/permission requirements, but the behavioral picture is unusually complete.

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 upsert behavior, then layered with validation, dryRun, no-delete, and integration-guide guidance. Five sentences is on the long side, but each one carries distinct, non-redundant information; minor trimming of the get_integration_guide aside would tighten 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 complex nested upsert tool with no output schema, the description covers the write model, atomicity, dry-run diff semantics, deletion policy, and cross-tool workflow. An agent has everything needed to invoke it safely and interpret the outcome without an output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it identifies the exact source and shape of the `flags` payload (the array from export_feature_flags / CLI bridge flag export) and explains dryRun's diff output including which fields differ.

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 (apply/import a flags-as-code bundle) and immediately defines the upsert semantics: creates missing flags, updates existing ones, matched by key. This clearly separates it from create_feature_flag, update_feature_flag, and export_feature_flags, which it explicitly names.

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 guidance: set dryRun first when importing a bundle you did not just export; use delete_feature_flag for extraneous flags rather than this tool; call get_integration_guide before writing app code. It names alternatives and the conditions that select them.

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

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

Adds real behavior beyond the annotations: it creates the user AND sends an invitation, returns the new user, and discloses a notable quirk (role missing means no invite and a DECISION_NEEDED response listing role keys rather than silently applying a default). It doesn't discuss auth requirements or idempotency, but the annotation already covers idempotentHint.

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 core action leads, followed by argument intent, then prerequisite/follow-up guidance. Nearly every sentence earns its place, though the argument-list and next-step guidance could be tightened slightly.

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 mutation tool with no output schema, it covers the key parameters, prerequisite (create_tenant), alternative (update_user), and return value ('Returns the new user'). The unmentioned 'app' parameter and absence of auth/permission notes are minor gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: role is a KEY from list_roles and must be the developer's explicit choice, tenantName is the NAME from list_tenants while tenantId comes from create_tenant, and firstName/lastName appear in the invitation. Only the 'app' parameter is left 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?

States a specific verb (invite) and resource (person into a tenant/customer workspace) and clarifies that Bridge creates the user and sends the invitation. It explicitly distinguishes itself from create_tenant and update_user, so an agent can route correctly 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/when-not and alternative routing: use create_tenant first when the tenant doesn't exist, update_user to change an existing member's role, and get_integration_guide before writing consuming code. This is exactly the routing guidance 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real value by disclosing that token secrets are NOT returned and are only shown once at creation — a critical behavioral fact. It does not mention pagination or result-size limits for a list operation, which keeps it from a 5.

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

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

Three sentences, front-loaded with the action and scope, then the return fields, then the routing guidance. The field enumeration is dense but earns its place given no output schema exists.

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

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

With no output schema, the description compensates by enumerating returned record fields (id, name, privilege keys, tenant scope, expireAt, lastUsedAt, createdAt). Only pagination/ordering behavior is left 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?

There is one optional parameter with 100% schema description coverage, so the schema fully documents 'app' including the 'omit to use the current app' behavior. The description adds nothing about the parameter; baseline 3 applies.

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

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

States a specific verb and resource ('List every API token issued for the Bridge app') and immediately contrasts with create_api_token and revoke_api_token, so an agent can distinguish it from siblings 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-to-use guidance: check which privileges a token carries (including whether it may perform destructive operations) and find the token name that revoke_api_token requires. It also states the alternative path for secrets (create_api_token).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the `current: true` marker semantics and how visibility differs between a workspace-approved connection and a single-app connection, including apps created after connecting.

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 verb and resource, then three tight sentences covering the current marker, scope, and next-step usage. Slightly dense with detail but every sentence adds actionable information; 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 no parameters, the description carries the full burden and does so: it describes the returned list (apps with ids, a current marker) and the visibility model. Nothing an agent needs to interpret the output or proceed 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?

Zero parameters, so baseline is 4. The description compensates well by explaining what the returned ids are for and how to feed them into the `app` argument, adding meaning that an empty schema cannot carry.

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 apps) and scopes it precisely: 'the Bridge apps this connection can work on, with their ids.' The visibility rules (workspace-wide vs single-app) differentiate it from siblings like get_app, and an agent knows exactly what comes back.

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

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

Explains the downstream usage condition clearly: pass an id as the `app` argument of any tool for a single call, or call use_app to change the default. This routes the agent to the right alternative (use_app), though it doesn't state an explicit 'don't use X, use this instead' exclusion beyond that.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: the event field set, the TENANT_NOT_FOUND failure mode, and that tenantName is resolved to an id internally. It stops short of ordering, default limit, or pagination behavior, which an agent would benefit from.

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

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

Front-loaded with purpose, then return shape, then filters, then debugging guidance and error routing — a logical order. The dense single paragraph with em-dashes and parentheticals is slightly heavy but nearly every clause carries routing or semantic value.

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 filter-list tool with no output schema, the description covers filters, the fields returned, and the one failure mode, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so type/since/limit/tenantName are already documented and the description largely restates them. It adds marginal value by noting tenantName is a NAME resolved to an id and by tying tenantName to the TENANT_NOT_FOUND error, but this does not exceed the baseline for full-coverage schemas.

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?

Starts with a specific verb+resource ("Query the Bridge app event log") and immediately scopes it with concrete event categories (signups, logins, lifecycle events). The agent can distinguish it from state-inspection or auth-debugging siblings 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 frames the when-to-use ("debug what actually happened … rather than inferring it from state") and names alternatives with their triggers: list_tenants for resolving names, debug_auth_issue for sign-in failures. Both the positive case and the exclusions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, destructiveHint=false, so the safety profile is largely covered. The description adds meaningful context beyond annotations: it documents the per-flag fields returned (including 'warnings' on suspicious flags), notes it lists 'every' flag in the app, and explains edge-case semantics (numbers are plan quotas, permission on a record stays in app code). It doesn't state pagination or limits, which would be useful for a list-all tool, so not a 5.

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

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

The front of the description is tight and useful (purpose, fields, when-to-use, alternatives). However it then drifts into a lengthy conceptual primer about flags vs privileges vs roles vs plans vs quotas, which is better suited to the referenced integration guide than the tool definition, diluting conciseness.

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

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

For a read-only list tool with a single optional param, full schema coverage, and no output schema, the description gives enough to call it correctly: what is listed, what each entry contains, and when to choose it over siblings. The only material gap is list behavior (ordering, pagination, size limits).

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

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

Only one optional parameter (`app`), and schema description coverage is 100% — the schema already says to omit it to use the current app. The description doesn't add syntax about `app`, but with a single well-documented optional param, the baseline is high; the description's mention of 'the Bridge app' contextualizes scope without repeating 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 (List) and resource (feature flags), scoped to the 'Bridge app', and enumerates the returned shape (key, description, lifecycle state, value type, targeting rule tree, scheduled transition, source, warnings). This makes it clearly distinct from get_flag (single flag), create_feature_flag, and update_feature_flag.

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

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

Explicitly says when to use it ('verifying a flag key exists before referencing it in code, or inspecting targeting before relying on a flag') and names alternatives for adjacent jobs: get_app/get_auth_config for app-level auth/config, get_environment_info for project wiring, and get_integration_guide topic=fit-together for the full 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 cover read-only/idempotent/non-destructive, yet the description adds real behavioral detail: the dedup rule ('every metric ... once each, with the plans that limit it'), the semantic meaning of kind counter vs gauge, limit=0 meaning pure metered billing, policy hard vs metered, and the PLAN_NOT_FOUND failure mode. This is substantial context beyond the 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?

Purpose and the two modes are front-loaded, and every clause is informative. The dense parenthetical explaining kind and the return-field enumeration make it longer than strictly necessary, but the content largely earns its space.

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 properly carries the return-value burden, enumerating each quota field (metric, kind, limit, policy, pricing, source, reportWith) and its meaning, plus the error case. An agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description meaningfully enriches planKey by explaining the shape of results in each presence/absence case and giving an example value ('pro'). The app parameter is not elaborated in the description, but the schema already documents it.

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

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

States a specific verb and resource ('List usage-quota metrics with their kind') and immediately contrasts the two modes: with planKey returns that plan's quotas, without planKey returns every metric deduplicated across plans. It explicitly names the sibling it is not ('set_plan_quota changes one'), so an agent can separate read from write without opening a schema.

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

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

Gives clear usage context ('Use this when wiring quota checks or usage reporting') and routes to the mutation alternative (set_plan_quota). It does not state explicit when-not conditions beyond naming the read/write split, so it falls just short of the 5-level 'explicit when/when-not/alternatives' bar.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description adds real behavioral context: the meaning of archived: true (workspaces already on it keep it, nobody new can choose it). It also discloses the returned field structure. It stops short of pagination/size behavior, which keeps it from a 5.

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

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

Front-loaded with the core action and scope, and the guidance/alternatives come after. It is dense and somewhat long, with an itemized enumeration of every returned field, but each sentence carries routing or return-shape value rather than filler.

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

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

With no output schema, the description shoulders the burden of explaining the return shape and does so thoroughly (keys, trial, prices, features, per-metric quotas with policy/kind/source). Combined with the usage routing, an agent has everything needed to call it correctly.

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

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

Only one parameter (app) and schema description coverage is 100%, so the schema already documents it ('Omit to use the current app'). The description adds nothing specific about the app parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource (list subscription plans in the Bridge app) and immediately names the scope of what is returned: prices, features and quota properties. It is clearly distinguishable from get_plan (singular), list_plan_quotas and the mutation siblings like apply_plan/delete_plan.

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 ('billing, entitlement and quota questions'), gives concrete triggers (which plan key to reference in code, what a plan includes, what limits it enforces), and names the alternatives for adjacent jobs: add/remove/set_plan_features, apply_plan, get_app, delete_plan.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it lists privileges no role grants yet (completeness of the listing), notes that role capability is only the app's default until read here, and warns that a privilege rule matches the whole key ('REPORTS_VIEW' does not match REPORTS_VIEW_ALL').

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 routing are front-loaded, which is good, but the description drifts into app-design guidance not needed to invoke the tool ('never with a hard-coded role check in app code') and a somewhat cryptic line about defaults. Roughly a third of the text does not help an agent select or call this tool.

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 tool with no output schema, the description covers purpose, return fields, sibling differentiation, and downstream workflow use. 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?

Only one optional parameter (app) and schema description coverage is 100%, so the schema already documents the omit-to-use-current-app behavior. The description adds nothing about the parameter beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List every privilege defined for the Bridge app') and enumerates the returned fields (id, key, description). It explicitly separates itself from the closest sibling by noting 'list_roles shows which privileges each role grants.'

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 trigger conditions and named alternatives: 'Use this before create_role / update_role, before gating a flag rule on a privilege, or to find the key for update_privilege or delete_privilege.' Nothing is left to inference about when this tool is the right 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 read-only/idempotent/non-destructive, so 'Read-only' is largely redundant, but the description adds genuine behavioral context: the URL must match EXACTLY including scheme, port and path, and that add/remove preserve the rest of 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?

Front-loaded with the core purpose and safety, then usage and cross-references. Every sentence carries information, though it is somewhat dense with multiple distinct instructions packed into one block.

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

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

For a read-only single-optional-parameter list tool with no output schema, the description covers purpose, safety, exact-match semantics, related mutations, and the recommended follow-up guide call. 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 description coverage is 100% and the app parameter is already fully documented in the schema (id source, omit-to-use-current behavior). The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource (list OAuth redirect/callback URIs) and immediately scopes it to the Bridge app, distinguishing it from the sibling add_redirect_uri and remove_redirect_uri by naming them.

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

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

Gives an explicit when-to-use trigger (diagnosing a redirect_uri mismatch login failure), names the mutation alternatives with their effect on the list, and points to get_integration_guide with a specific topic before writing app code.

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 read-only/idempotent profile, but the description adds real behavioral context beyond them: default roles are merely a suggestion the developer can rename/re-scope, names should not be trusted, and rule matching is whole-key (REPORTS_VIEW does not match REPORTS_VIEW_ALL). It also warns against hard-coded role checks. This is meaningful disclosure; it stops short of full richness (e.g. pagination/ordering) but is well above the annotation baseline.

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 return shape, then usage, then caveats. It is fairly long and dense, but nearly every sentence carries distinct value (return fields, usage triggers, rule-matching gotcha). Could be trimmed slightly without losing 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?

With no output schema, the description fully carries the burden of describing return values, enumerating each role field and explaining the top-level privileges map. It also covers the absence of assumptions and the access-control model, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the single 'app' parameter is fully documented in the schema, so the baseline is 3. The description adds no syntax or format detail for the parameter beyond what the schema already provides.

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 every access role in the Bridge app with its privileges') and distinguishes itself from siblings by naming get_role-adjacent alternatives such as get_auth_config and get_app. An agent can tell it apart from list_privileges or get_role 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 enumerates when to use it (before writing a flag rule targeting a privilege/role, when choosing which role to assign a user, when verifying a privilege key exists) and names alternative tools for adjacent needs (get_auth_config, get_app). Both the trigger conditions and the exclusions are stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely useful behavior: the critical name-vs-id addressing rule and the exact fields returned, which matters since no output schema exists. It omits pagination/limit behavior, 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-loaded with purpose, then return fields, then usage routing. The field enumeration is long but earns its place because there is no output schema. Structure is clean with no wasted sentences.

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

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

Given no output schema, the field list usefully substitutes for return documentation, and annotations cover safety. The only small gap is absence of pagination/volume behavior for a 'list every tenant' call. Otherwise complete for a simple list 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 the single 'app' parameter is fully documented in the schema. The description adds no parameter-level detail of its own, which is the expected baseline when the schema does the work.

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

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

States a specific verb+resource+scope: 'List every tenant (workspace/customer account) in the Bridge app.' It even clarifies the domain term 'tenant', and clearly distinguishes itself from get_tenant/list_users by contrast.

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

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

Explicitly states when to use it: to discover tenant names before calling get_tenant/update_tenant/delete_tenant because those address tenants by NAME, not id. It also routes to the sibling list_users for users within a tenant. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them by disambiguating three easily-confused timestamp fields (lastSeen is account activity NOT a login, lastSignIn is account-wide, lastWorkspaceSignIn is this workspace) and by naming the two failure modes (TENANT_NOT_FOUND, TENANT_AMBIGUOUS). That is exactly the kind of interpretation guidance an agent cannot get 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?

The purpose is front-loaded in the first clause, and every sentence carries substantive information rather than filler. The long enumerated field list makes it slightly dense/run-on, but nothing is wasteful.

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, and the description compensates by enumerating the returned fields and their semantics, plus the error conditions. For a two-parameter read-only list tool, an agent has everything needed to call it and interpret the result 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%, so both parameters are already documented at baseline. The description reinforces that tenantName comes from list_tenants and accepts an id as fallback, but adds no syntax beyond what the schema states, and says nothing about the optional '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 (list users) scoped to exactly one tenant, and specifies the tenant is addressed by NAME. An agent can immediately distinguish it from get_user, invite_user, and list_tenants 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 names the prerequisite tool for obtaining the required argument (list_tenants) and gives a concrete downstream motivation: 'discover the email addresses the other user tools take.' It does not explicitly contrast with get_user or say when a single-tenant listing is insufficient, but the context 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 readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description goes well beyond them by disclosing the downstream consequence (workspaces lose the entitlement and flags gated on `bridge:billing.entitlement.<featureKey>` turn off), the specific error code, and the return shape ('Returns the full plan'). This is exactly the context needed to decide whether to warn a user before invoking.

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 is front-loaded, followed by effects, errors, alternatives, and return value, so an agent gets the essentials immediately. It is a dense block of seven clauses and the trailing get_integration_guide instruction is slightly beyond invocation scope, keeping it just short of a 5.

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

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

With no output schema, the description compensates by stating the return value ('the full plan'), the error behavior, the downstream entitlement effect, the sibling alternatives, and the integration-guide prerequisite. Nothing an agent needs to invoke 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 description coverage is 100% (key, feature, and the optional app param are all documented in-schema), so the baseline of 3 applies. The description confirms that `feature` is matched by feature key and that `key` refers to a plan, but adds no syntax, format, or guidance about the optional `app` override.

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 ('Take an on/off feature off a plan by its feature key') with scope ('other features are kept'). It also names the reciprocal sibling add_plan_feature and list_plans, so an agent can distinguish it from the other plan 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?

Explicit alternatives are given ('Use add_plan_feature to add one and list_plans to see every plan's features'), plus a failure condition (FEATURE_NOT_FOUND) and a prerequisite workflow (call get_integration_guide with topic=billing before writing consuming app code). Both when-to-use and when-not paths 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real context on top: the exact error code raised, and that removal is narrowly scoped so sibling prices survive. It does not mention auth or permission requirements, but the added failure and blast-radius detail is substantive.

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 its identifiers, then the failure mode, then the cross-tool pointer. Three tight sentences with no filler, though the integration-guide sentence is somewhat tangential to the invocation itself.

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 present and no output schema, the description supplies what is missing: the error case, the preservation guarantee, and the follow-up guide pointer. An agent has enough to call it correctly; only explicit permission or auth prerequisites are absent.

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

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

Schema description coverage is 100%, so the schema already documents key, app, currency, and interval. The description restates the interval enum and the USD default rather than adding new semantics, so the baseline of 3 applies.

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

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

States a specific verb (Remove) plus the precise resource slice (a recurring price on a plan) and the two identifying dimensions (interval, currency). It is clearly distinguishable from set_plan_price and from the adjacent remove_plan_feature / remove_plan_quota 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?

Gives a concrete failure condition (PRICE_NOT_FOUND when no price matches currency + interval) and the scope of the change (other prices preserved), which tells the agent what to expect before calling. It also routes the agent to get_integration_guide for downstream app code, though it never explicitly contrasts itself with set_plan_price for the overwrite-vs-remove decision.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the description's job is to add context beyond that. It does: it discloses the QUOTA_NOT_FOUND failure mode and the important scoping guarantee that other quotas are preserved, which makes the non-destructive annotation credible rather than surprising.

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 compact sentences that lead with the action, then the failure mode, then the workflow pointer. Nothing is redundant, though the integration-guide sentence is arguably tangential to invoking this tool correctly.

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

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

With no output schema and a fully documented input schema, the description supplies what structured fields cannot: the error contract and the preservation semantics. It omits only minor details such as whether the plan itself or its cached state is affected.

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

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

Schema description coverage is 100%, so all three parameters (app, key, metric) are already documented in-schema as pointers to list_apps and list_plans. The description only echoes 'metric key' and adds no format, defaulting, or scoping detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Remove a usage quota from a plan') and pins the addressing key ('by its metric key'). An agent can distinguish this from sibling mutations like set_plan_quota or remove_plan_feature, though the description never names the counterpart tool 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?

Gives a concrete precondition for failure (QUOTA_NOT_FOUND when no quota exists for that metric) and a workflow directive to call get_integration_guide with topic=billing before writing app code. It lacks an explicit 'use set_plan_quota instead when you want to change rather than drop a quota' routing 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?

Goes well beyond the annotations: it discloses exact-match semantics (scheme, port and path must match), the specific failure mode and error code (REDIRECT_URI_NOT_REGISTERED, which even lists the currently registered URIs), and that all other URIs survive. This is materially richer than the readOnly/destructive/idempotent 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?

Front-loaded with the core action and its non-destructive scoping, followed by failure behavior and cross-references. Dense and largely waste-free, though the trailing get_integration_guide instruction pushes slightly beyond the tool's own 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?

With no output schema, the description still covers the success behavior (only the one URI removed), the error path, and the matching rule for both parameters. An agent has everything needed to call this correctly without inspecting siblings.

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 on top: it clarifies that the match is exact including scheme, port and path, and that the value must be exactly what list_redirect_uris shows. It adds nothing for the optional 'app' parameter, keeping it short of a 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 (unregister/remove) and resource (ONE OAuth redirect callback URI on the Bridge app) with explicit scope ('preserving every other registered URI'). It is immediately distinguishable from add_redirect_uri and list_redirect_uris.

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 counterpart tool ('Use add_redirect_uri to register one') and prescribes a companion call (get_integration_guide with topic=auth) before writing consuming code. It gives clear context for when to reach for it, but never states an explicit when-not or prerequisite condition (e.g. required permissions).

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

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

Annotations declare destructiveHint=true but the description goes well beyond them: it flags IRREVERSIBILITY, the confirmation requirement, the exact-failure conditions (tenant/email not resolving to exactly one record, confirmation mismatch), and dryRun side effects (login account removal, last-owner detection). This is rich behavioral context beyond the structured 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?

The safety-critical facts (IRREVERSIBLE, REQUIRES CONFIRMATION) are front-loaded and the alternative path and dryRun guidance follow in logical order. Despite its length, every clause carries actionable weight.

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 5-parameter tool with no output schema, the description covers prerequisites, failure modes, the safe preview path, the alternative operation, and follow-on tooling. An agent has everything needed to call this correctly and safely.

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: confirm must equal the exact email address and must follow explicit user consent, and dryRun previews without needing confirm. It reinforces rather than merely restates 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 with scope: 'Remove a user from a tenant, revoking their access to it.' It also implicitly distinguishes itself from the suspension path by naming update_user, so an agent can route correctly 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?

Explicit on when to use vs alternatives: use update_user with enabled=false if access should merely be suspended. Lays out the required two-step confirm flow, mandates dryRun preview first, and points to get_integration_guide for app integration. 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 declare destructiveHint=true, but the description goes well beyond them: irreversibility ('cannot be restored, only replaced'), the mandatory confirmation protocol, the specific failure modes (TOKEN_NOT_FOUND, TOKEN_AMBIGUOUS, mismatched confirmation) with the guarantee nothing is revoked, and that dryRun needs the same privilege as the deletion.

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 irreversible warning and confirmation requirement in the first two sentences, and information-dense throughout. It runs long, and the trailing get_integration_guide instruction is arguably tangential to the revoke action, keeping it just short of a 5.

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 tool with no output schema, the description supplies everything needed: safety protocol, irreversibility, failure semantics, preview behavior, and named sibling prerequisites. An agent can invoke it correctly on the first try without further exploration.

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, and the description earns an extra point by making the interplay explicit: confirm must equal the exact token name and is not needed with dryRun, and dryRun reveals privileges, last use, and whether the token backs the current connection. It adds workflow meaning rather than just restating parameter docs.

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 ('Revoke an API token by NAME') plus the scope of impact ('permanently disabling every client authenticating with it'). It names the counterpart sibling create_api_token and the prerequisite sibling list_api_tokens, so an agent can place it precisely among the many delete/remove 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?

Gives an explicit ordered workflow: list the tokens first, then call with confirm set to the exact token name, and only after the user has explicitly agreed. It also states when to use dryRun (preview first) and when to call get_integration_guide, covering both alternatives and preconditions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds real context beyond them: it enumerates exactly what is returned (config contents, install command, setup guide), confirms nothing is written to disk or the Bridge app, and notes the base URL is read live from the current Bridge app. It also discloses that the guide is fetched from the plugin repo that owns it.

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?

Long but every sentence carries distinct weight: purpose, return payload, no-write guarantee, usage routing, framework detection, guide dedup, and an import-specifier warning. Purpose and the CLI analogy are front-loaded, with operational detail following.

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 explicitly, plus it removes the main ambiguity (does it write? is it required to pass framework?) for a scaffold tool. 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 100%, so the basics are covered, but the description adds a full framework-detection procedure (package.json mappings with an explicit check order) that the schema does not contain, and explains why framework is required. app/baseUrl/includeGuide get no additional meaning beyond their schema docs, keeping this out of 5 territory.

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 ('Scaffold a flags-only Bridge integration into an existing project') and anchors it to a concrete equivalent ('bridge flag init'). It explicitly distinguishes itself from the closest sibling by telling the agent to use get_integration_guide for auth/billing topics.

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

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

Gives an explicit trigger ('adding feature flags to a project for the first time'), names the alternative for other cases ('for auth or billing use get_integration_guide with topic=master or topic=billing-master'), and warns against a redundant call ('no need to call both'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare it non-readonly, idempotent, and non-destructive; the description adds substantial extra context on top: the side effect ('The previous default stops being the default'), the return value ('Returns the updated role'), and a specific failure mode ('Fails with ROLE_NOT_FOUND, listing the app's role keys'). This is rich disclosure beyond structured data.

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

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

The core purpose, argument, and side effect are front-loaded effectively, but the tail drifts into general authorization advice (hard-coded role checks, privilege-key matching semantics, integration-guide pointers) that does not directly help an agent invoke set_default_role. For a simple two-parameter mutation the description is padded.

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 covers the return value, the error case, the replaced-default side effect, and the prerequisite reads, which is nearly everything needed to call it. It omits any statement of required permissions/caller authority, which is the only notable gap.

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

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

Schema description coverage is 100%, and the schema already documents both 'app' and 'key' with the exact 'Role KEY from list_roles, e.g. MEMBER' wording. The description repeats that phrasing rather than adding syntax or format detail, so the schema does the heavy lifting and the baseline of 3 applies.

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

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

States a precise verb and resource ('Make an existing role the default') and immediately defines the concept ('the role a person gets when they are added to a workspace without a role named'). An agent can distinguish this from siblings like create_role, update_role, and get_role without opening a schema.

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

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

Gives clear context: read roles with list_roles first, ask the developer rather than picking a default, and call get_integration_guide before writing consuming code. It names prerequisite/related tools, but does not explicitly contrast this tool against the closely-related update_role, so the routing is slightly incomplete.

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

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

Annotations declare non-read-only, idempotent, non-destructive, closed-world, but the description adds genuinely new behavior: the write does not alter the flag's current state until the timer fires, that setting a schedule overwrites any existing schedule (a side effect the destructiveHint=false hint does not convey), and the FLAG_NOT_FOUND failure mode. This is meaningful disclosure beyond the 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?

Front-loaded with the core action and the semantics that follow, and most sentences carry non-obvious information. The 'Arguments:' sentence largely duplicates the schema and the get_integration_guide pointer is slightly tangential, so it is efficient but not maximally tight.

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 mutation tool with no output schema, the description covers effect on current state, replacement semantics, error behavior, and an integration prerequisite — everything an agent needs to call it correctly without follow-up. Return-value detail is unnecessary since no output schema exists.

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