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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that each call is charged in USDC from a configured wallet, constrained by budget caps, and that output is third-party data rather than instructions — meaningful behavioral context an agent could not infer from structured fields. It omits failure/refund behavior and the response shape, and it conflicts with the schema on max_tokens limits (4000 via MCP vs 'max 32000' in the schema), which leaves the real ceiling ambiguous.

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 pricing and payment constraints are front-loaded, and each sentence carries a distinct fact (price, cap, payment, untrusted output). The pricing clause is somewhat dense with repeated phrasing ('priced per request' / 'quoted per request'), but nothing is 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?

For a 9-parameter paid tool with nested objects and no output schema, the definition covers the economically critical facts: cost, spend limit, the 4000-token MCP ceiling, quote-first workflow, and prompt-injection caution. The unresolved 4000 vs 32000 max_tokens discrepancy and the absence of any return-value description are the remaining 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 44% schema coverage across 9 parameters, the description partially compensates by explaining that max_tokens doubles as the spend limit and is capped at 4000 through MCP, and by tying pricing to messages and max_tokens. It says nothing about seed, stop, top_p, temperature, response_format, or model selection, leaving several parameters documented only by terse or absent 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?

The description states a specific verb and resource ('Chat completion from maxwell-chat') and immediately scopes it as a paid per-request LLM call, which separates it from siblings like llm_models and get_price_quote. It does not name any other chat-adjacent sibling it might be confused with, but the purpose 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?

It gives an explicit prerequisite workflow: 'Use get_price_quote first to see the exact price,' and explains the confirm_over_cap path for clients that cannot prompt the user. It does not state when NOT to use this tool (e.g., free alternatives or offline use cases), so it stops short of full routing guidance.

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