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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=false, and the description restates the idempotency contract rather than adding much (the two closing sentences describe the same behaviour). It adds no information about permissions, validation failures, or what happens to the owner assignment. No annotation contradiction: "adds" matches readOnlyHint=false.

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 purpose sentence is well front-loaded and dense. However, the second and third sentences are near-duplicates of each other and of the idempotentHint annotation, so roughly a third of the text is wasted.

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 write tool taking a nested body of ~15 fields with no output schema, the description leaves key questions unanswered: what is returned (deal id?), how closed-won/lost states interact with the reason fields, and what cardId must reference. The annotation set covers safety but not these functional details.

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 description coverage is only 33%, so the description carries the burden and largely fails it. It lists field names (name, type, status, amount, currency, dates, owner) but adds no meaning beyond them — nothing about cardId identifying a company, provided-vs-defaulted values, conditional requirements such as win/loss reasons when status is won or lost, or the native-vs-reporting amount distinction.

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 opens with a specific verb+resource ("Adds a new manual deal to a pipeline company") and enumerates the payload fields, so an agent immediately knows this is the creation path for deals. The word "manual" usefully implies contrast with automatically-sourced deals (e.g. listDealCandidates), though no sibling tool is actually named.

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: it is a create operation, and the last two sentences define retry behaviour (reuse the key only to retry the same call). There is no explicit guidance on when to use this versus updateDeal/moveDeal, nor any stated prerequisite such as needing the company's cardId.

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