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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds only a generic 'tenant-scoped' boundary and a broad resource list. It does not explain what happens when the tool is called, what fields are affected, or why the operation is read-only despite the 'update_line' name.

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 short, but its single sentence is an unfocused list of resource types rather than a purposeful summary. It does not front-load the key action or make efficient use of the sentence to convey what this specific tool does.

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?

This is a complex tool with 13 optional parameters and nested object inputs, yet the description gives almost no operational context. The output schema may cover return values, but the agent is left without any understanding of how to construct a valid call or what the tool is actually for.

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 only 15% schema description coverage and 13 mostly undocumented parameters, the description needed to provide substantial parameter context. It provides none, leaving line, lines, query, bridge, format, approval, source_id, document_id, estimate_id, progress_pct, and idempotency_key with almost no meaning beyond their names.

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 uses the vague verb phrase 'Operate on' and lists a broad set of resources (drafts, lines, versions, documents, exports, policy receipts) without stating that this tool specifically updates an estimate line. It fails to convey the tool's core action and does not distinguish it from the many sibling estimator tools.

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?

There is no guidance about when to use this tool, what conditions are appropriate, or when to prefer a sibling like estimator_estimate_add_line. The description provides no decision-making context, leaving the agent to infer usage from the tool name alone.

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