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

Annotations only declare destructiveHint=true, so the description carries most of the burden and does well: the 'WRITE:' prefix, the partial-update guarantee ('only the fields you pass are sent'), and the required-field quirk (first_name/last_name must be passed even when unchanged) are all behavior an agent cannot infer from the schema alone. It stops short of describing permissions, error behavior, or what an empty PATCH returns.

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 dense sentences, front-loaded with the operation type and field scope, followed by the two gotchas an agent must know. The trailing 'LGL: PATCH /api/v1/constituents/{id}' is compact and useful. No filler, though the field enumeration slightly overlaps the 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 22-parameter mutation with no output schema, the description covers the highest-risk unknowns: partial update behavior, the required-name trap, and excluded sub-resources. Return value and failure modes are unstated, but with no output schema that omission is defensible; the main residual gap is the undocumented minority of fields.

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 59%, with parameters such as gender, suffix, job_title, is_deceased, maiden_name, middle_name, deceased_date and annual_report_name undocumented in either place. The description adds real value on the required-first_name/last_name wrinkle and the send-only-what-you-pass semantics, but does not fill the documentation gap for the remaining undocumented fields, so this lands at the baseline-plus level rather than higher.

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 ('change scalar fields on an existing constituent') and enumerates representative fields, so the scope is immediately legible. It also draws the boundary against sibling functionality by declaring that addresses, emails and phones are not edited here, which no sibling name alone would convey.

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?

Gives clear operational context: only passed fields are sent, and current values should be sourced from lgl_get_constituent when first_name/last_name are unchanged. The exclusion of addresses/emails/phones implies an alternative path but never names the tool that handles them, so the routing is clear but not fully explicit.

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