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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description goes further by disclosing the quota model (10 free calls/day, then $0.003/call) and the three accepted payment paths (x402 via params._meta, HTTP x402, X-API-Key credits). That is real behavioral context an agent cannot get from structured fields. It stops short of noting failure modes such as unreachable URLs or malformed YAML.

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 the linting scope, then the commercial terms. Every clause carries information: the check list is dense but each item is a distinct lint category. The trailing "[served by tools.moneytools.dev]" is borderline filler but small. Slightly telegraphic, requiring the reader to parse a comma-separated list rather than prose.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The gap is that the schema marks both parameters optional with no required fields and the description never states that one of url or spec must be supplied, nor what happens if both are given; for a two-input tool that ambiguity is the main thing an agent needs resolved before calling.

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% and both parameters carry descriptions ("spec URL", "or the spec (JSON object or YAML string)"), so the baseline is already 3. The description reinforces the accepted formats (JSON or YAML) and, together with the schema's "or the spec" phrasing, conveys that the URL and inline-spec inputs are alternative supply modes. Little meaning is left unexplained beyond which of the two to prefer.

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?

A concrete verb ("Lint") applied to a concrete resource (OpenAPI/Swagger JSON or YAML), followed by an enumeration of the specific checks (operationIds, descriptions, responses, undeclared path params, security schemes, servers, x402 payment info). An agent knows exactly what output classes to expect. It does not, however, distinguish itself from the sibling mcp_tools_lint, which by name alone could appear to cover the same territory.

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 is only implied: the title's "agent readiness" framing and the list of checks suggest this is the tool for validating that an API spec is machine-consumable, and the url/spec pair implies two input modes. There is no explicit when-to-use statement, no stated prerequisite (e.g., that the spec must be reachable or under size limits), and no routing guidance versus mcp_tools_lint.

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