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

Annotations already cover readOnly/openWorld/destructive, so the description adds value by disclosing that all filters are optional and combine with AND, and by enumerating the result row fields — important since there is no output schema. It does not mention pagination caps or result limits beyond what the schema says.

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?

Two substantive sentences front-load purpose and the alternative, with the endpoint as a trailing technical note. The field enumeration is slightly listy but earns its place given the absence of an output schema.

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 21-parameter, zero-required search with no output schema and no annotations gap, the description supplies the two things the schema cannot: AND-combination semantics and the shape of returned rows. Nothing critical is missing, though error behavior and search-match semantics are left to the schema.

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 contributes a genuinely non-schema fact: filters are all optional and are AND-combined, which governs how to compose 21 parameters. It adds no per-parameter detail beyond that.

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 ('Search contacts') and immediately scopes what a contact is ('customers, suppliers and staff'). It also names the sibling brightpearl_get_contacts as the full-record alternative, so an agent can distinguish the two without opening either schema.

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?

Explicitly routes the agent to brightpearl_get_contacts 'for the full record', which is the key alternative among the 24 siblings. It does not state when-not-to-use conditions (e.g. prefer exact_primary_email lookups versus name search), so it falls short of a 5.

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