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

The description contradicts the idempotentHint=false annotation by stating that Propstack matches on email and updates an existing contact instead of creating a duplicate, which makes repeated identical calls effectively idempotent. Although the description usefully discloses the upsert behavior, return value, and consent-flag limitation, the direct conflict with the structured annotation forces a score of 1.

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 front-loaded with 'WRITE: create a CRM contact', then covers the key behavioral facts in three compact sentences plus the endpoint. For an 18-parameter tool, it is appropriately sized and every sentence contributes useful information.

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?

It covers the most important context an agent needs: that this is a write, the email-based upsert behavior, the return value, and a field limitation. It stops short of explaining permission requirements, partial-update behavior for omitted fields, or what happens when email is absent, but annotations cover the safety profile and the schema covers all parameters.

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 100%, so the baseline is 3, but the description adds important semantic context by identifying email as the matching key rather than merely a 'primary email address'. It also adds a constraint about consent-related fields that are not part of 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 states a specific verb and resource ('create a CRM contact') and immediately clarifies the matching behavior on email, which distinguishes its upsert semantics from a plain create. It also names the boundary condition (existing email is updated) that separates it from other sibling tools like propstack_update_contact.

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?

It gives clear context for use (create a CRM contact, matched by email) and an explicit exclusion ('Consent flags ... cannot be set here'). However, it does not name an alternative tool for the excluded consent flags or for ID-based updates, leaving the agent to infer routing to propstack_update_contact.

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