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

Annotations already declare the safety profile (idempotent, non-destructive, non-readOnly), so the description's added value is the boundary that it is a proposal which cannot approve a bid or production, plus the rule that supplier proof must come from reusable company context. However it omits revision-conflict behavior and the idempotency replay contract, which matter for a mutating, revision-gated submit.

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?

Three dense sentences with the purpose front-loaded, followed by content requirements and then the authority boundary. Every sentence carries information; slightly compressed but no filler.

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, deeply nested mutation tool with no output schema and 40% param coverage, the description covers purpose, sourcing rules, and authority limits but leaves revision/conflict handling and several sub-object semantics to the schema. Adequate but with visible 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?

Schema coverage is only 40%, so the description must compensate. It usefully maps to several nested qualification fields (mandatory conditions with 'unknown stays unknown', sourced deadlines, missing annexes, strategy, proposed blocks) and hints at revision alignment via 'the exact current analysis', but says nothing about analysisRevision/expectedRevision or idempotencyKey semantics.

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 verb ('save/submit') and resource ('sourced qualification') scoped to 'the exact current analysis', and distinguishes the action from approval work ('cannot approve a bid or production'). This lets an agent separate it from read_qualification, but it does not explicitly name which sibling to prefer.

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?

Provides implied usage context ('Save your sourced qualification', 'This is a proposal') and a sourcing constraint, but never states when to use this versus read_qualification, submit_analysis, or the approval tools. No explicit when/when-not or alternative routing is given.

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