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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description goes well beyond them: sandbox isolation, no network/secrets/database binding, worldwide budgets (100/min, 5000/day), per-client limits, 20 catalog calls, max 2 concurrent, 5s wall time, 50ms CPU, 32KiB code, 64KiB output, and JavaScript-only with no imports or TypeScript syntax. This is exactly the operational context an agent needs 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?

Front-loaded with purpose, then example, then constraints, then routing — a sensible ordering with no filler sentences. The hard-limits run is dense and slightly overwhelming in one block, but every clause carries an enforceable constraint, so nothing is truly 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 high-complexity sandbox tool the description covers capability, available methods, example usage, isolation guarantees, all enforced limits, and the runtime restrictions (JavaScript only, no imports/TS). An output schema exists, so it correctly omits return-value documentation.

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

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

Schema coverage is 0% for the single `code` parameter, so the description must carry the semantic load, and it does: it specifies that the value is an async function body, that it must return a small JSON value, gives a runnable example, and enumerates what the code may call and what it may not (no imports, no TS). The 32KiB ceiling is echoed in maxLength, but the meaning of the code is entirely description-supplied.

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 (run) and resource (a JavaScript async function in an isolated sandbox) and immediately enumerates the catalog.* surface it can compose, which cleanly distinguishes it from the sibling tools that expose those same capabilities individually. An agent can tell it apart from catalog_search or offer_compare 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?

Usage context is clear: this is the composition/aggregation path over the catalog.* methods, with a concrete example showing a multi-step call, and the closing line routes the agent to /mcp?mode=code when only search + execute are wanted. It never explicitly states when NOT to use it (e.g. prefer the single sibling tool for one simple lookup), so routing is demonstrated rather than fully specified.

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