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

The annotation declares destructiveHint: true, but the description clearly indicates a non-destructive create operation ('Add a note', 'POST /api/v1/notes'). This is a direct contradiction. The description does mention the API endpoint and version, but the conflict with annotations severely undermines behavioral transparency.

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 three sentences long, front-loaded with the core purpose, and every sentence adds useful information (requirements, API version/endpoint). There is no wasted wording.

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 simple creation tool, the description provides essential context: purpose, required field, linking requirement, and API details. Since there is no output schema, it doesn't need to explain return values. It lacks info on permissions or error cases, but that's not critical here. The main issue is the annotation contradiction, which is scored separately.

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?

The schema already describes all parameters (100% coverage), so the baseline is 3. The description adds the key semantic constraint that the note must be linked to at least one of deal/person/organization/lead, which is not enforced in the schema. It also clarifies that content can be HTML or plain text. This adds value beyond the schema.

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 clearly states the tool's function: 'Add a note' with a specific resource (a note) and the ability to link it to deals, persons, organizations, or leads. This distinctly differentiates it from sibling tools like pipedrive_list_notes or pipedrive_create_activity.

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?

The description provides context on when to use the tool: content is required, and the note must be linked to at least one entity. It also notes the API version choice (v1) because v2 has no notes endpoint. While it doesn't explicitly name alternatives, the guidance is sufficient for choosing this tool over others.

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