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

With only destructiveHint=true in annotations, the description carries real burden, and it discloses a non-obvious behavioral gotcha (a deal with no users is invisible to agents) plus the dependency on fub_list_pipelines. It says nothing about auth requirements, error modes, or what the response contains, so it is good but not complete.

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 short sentences, each carrying distinct information: what it does, the dependent lookup, and the critical userIds constraint, with the API endpoint tacked on compactly. Zero 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 15-parameter mutation with no output schema and partial schema coverage, the description omits return-value information (e.g. the new deal id, which an agent would need for follow-up calls) and gives no guidance on the many optional date/commission fields. It covers the essential create path but leaves meaningful 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 description coverage is 47%, below the threshold where the schema can carry parameter meaning alone, so the description must compensate. It adds semantics for only two of fifteen parameters (stageId's source and userIds' practical requirement), leaving price, description, and the six date fields undocumented in both places.

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 and resource ('Create a deal in a pipeline stage') and points at fub_list_pipelines as the source for stage ids, which orients the agent within the sibling set. It does not explicitly contrast with fub_update_deal, so it falls just short of full sibling differentiation.

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?

Gives a concrete calling rule rather than just a purpose: stage ids must come from fub_list_pipelines, and userIds should be included or the deal is 'invisible to agents.' It stops short of stating when to prefer this over fub_update_deal or when not to create.

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