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

Annotations only carry destructiveHint=true; the description adds the genuinely important behavioral fact that Neon's Account Match may merge the new record into an existing account with the same name and email, which explains the destructive hint and warns the agent about duplicate-creation side effects. It also states the return value (new id). Missing auth/permission requirements, but strong for one annotation.

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 tight sentences with no filler: identity of the resource, the dedup/merge caveat with the sibling to check, and the return value plus endpoint. The merge warning, the most consequential detail, is not buried.

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 19-parameter creation tool with no output schema, the description covers the two account shapes, the duplicate/merge hazard, and the returned id. It stops short of documenting the many address/contact fields (left to the schema, which is fine) and says nothing about permissions or validation failures, but nothing essential for correct invocation is missing.

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 100%, so the schema already documents all 19 fields, including that company_name is required for COMPANY. The description's type/company_name framing and the optional primary-contact note echo that, adding only marginal meaning beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 constituent account) and enumerates the two supported shapes, INDIVIDUAL or COMPANY, so an agent can tell it apart from neon_update_account and neon_get_account. The 'Returns the new id' plus 'POST /accounts' phrasing pins down exactly what the operation is.

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?

Names a concrete precondition and alternative: check neon_list_accounts by email first, because Account Match may merge into an existing account with the same name and email. This is clear routing guidance, though it doesn't spell out the converse (prefer neon_update_account when the account already exists) or any when-not-to-use case.

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