filter_parties

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

The description reveals non-obvious behaviors: email uniqueness validation, type must match name fields, and the 'read-only' hint for validation. These go beyond the schema and annotations, which only state destructive hints are false. Missing error handling details, but the key validation trap is exposed.

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?

Compact and dense with information — three sentences cover all key points. The text is not overly verbose, though the 'use read-only when validation' phrase is somewhat cryptic. Overall it imparts maximum value per word.

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?

Covers the primary decision points (person vs org, email uniqueness, field mismatches) and gives an outline of what to provide. Does not mention pagination or response format, but for a create tool, the crucial context is validation constraints.Client's expectation of the created object is likely understood.

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?

Clarifies the conditional parameters (lastName/organisationName based on type), explains that firstName/lastName are ignored for organisations, and specifies the 'value' for tags. Not every parameter is described, but the critical ones (type, name fields, uniqueness) are covered. The schema already provides structure for address/contact objects.

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 action ('create a new party') and distinguishes between person and organisation subtypes. It does not name an alternative create tool (none exists), but the purpose is unambiguous. Could be tightened, but the verb+object is specific.

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 explicit instructions for person vs. organisation creation, notes the ignored fields for organisations, and ties the 'type' field to name-field requirements. The email-uniqueness validation is also a crucial usage constraint. It doesn't compare against other create tools, but as the only create-party tool, the guidance is sufficient.

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