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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, but the description goes far beyond that. It discloses that the backend persists the row, stamps a quoteId, and integrates with the marketplace funnel and attestation flow. It also openly states the scaffolded state—returning `{ ok: false, scaffolded: true }` until the backend lands—and precisely describes the auth failure mode (JSON-RPC error -32001, code MCP_API_KEY_REQUIRED, never reaching the tool). This level of disambiguation is exemplary and aligns with 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?

The description is longer than average but every section earns its place: purpose first, then parameter semantics, then behavioral details, then scaffold warning, then auth guidance. Front-loading the core action and listing inputs makes it scannable. The scaffold and auth notes are necessary given the tool's incomplete backend and security requirements. It is dense but not redundant.

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

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

For a complex write tool with auth, scaffold status, and 7 parameters, the description covers the essentials: what it does, what inputs to provide, what happens on success (persists, gets quoteId), what happens on failure (scaffold or auth error), and who can use it. It does not specify the exact success response format beyond quoteId, nor elaborate on idempotency or the attestation flow details, but these are minor gaps relative to the rich context provided. The annotations and schema fill remaining structured 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?

With 0% schema description coverage, the description is the only semantic source for parameters. It maps most parameters: 'cohort tier (AAA..CCC|NR)' to cohortTier, 'annual rate in basis points' to annualRateBps, 'term length in days' to termDays, 'maximum facility size in USD cents' to maxAmountUsdCents, and 'validity window' to validUntilIso. It also implies lenderId via 'authorised lender.' However, it omits agentBearer entirely and does not elaborate on format of validUntilIso beyond the name. This is substantial but not fully exhaustive.

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 specific verb+resource: 'Submit a draft credit-quote on behalf of an authorised lender.' It then enumerates the exact data captured (cohort tier, rate, term, amount, validity window), making the tool's function unambiguous. It distinguishes itself from read-only siblings by explicitly stating this is a write operation that persists data, and the auth section reinforces that it is not a public read. The scaffold caveat further clarifies its current role.

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

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

The description provides clear context: it is a write operation for authorised lenders, requiring a valid API key, and it is not on the public read tier. The scaffold warning tells the agent when it may fail and what to expect. However, it does not explicitly name alternative tools or state 'use this instead of X for Y'—it relies on the contrast between read and write operations and the auth requirement to imply usage boundaries. This is slightly above average but not fully explicit.

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