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 value beyond them: array values are JSON-encoded, cells beginning with = + - @ are escaped against formula injection, and the call costs $0.003 USDC via x402 on eip155:8453. The payment/auth requirement is exactly the kind of context annotations cannot express. It stops short of describing failure behavior on invalid JSON.

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+resource, then layered detail (union headers, flattening, escaping, pricing) in a compact two-sentence body. The opening phrase slightly repeats the title, and the pricing sentence is dense but earns its place since it affects whether the agent can call at all.

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 stateless pure-transform tool with no output schema, the description covers output shape (header row, column naming, escaping) and the payment gate, which is what an agent needs. The gap is the undocumented flatten=false and delimiter behavior, but the enum in the schema partially covers delimiter.

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 only 33%, so the description carries extra burden. It effectively explains the flatten behavior ('nested objects become dot.separated columns') but never says what flatten=false does, and the delimiter parameter and its enum options are not mentioned at all in the description. Partial compensation only.

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 transformation (JSON array of objects to CSV) plus the non-obvious scope: header row from the union of keys, dot-separated nested columns. The inverse sibling csv_to_json is trivially distinguishable by direction, so nothing is ambiguous.

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 implied by the direction of conversion, and the sibling csv_to_json makes the alternative obvious, but the description never states when to choose this versus csv_to_json nor any preconditions on input shape. An agent can infer it, but it is not spelled out.

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