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

Goes well beyond the annotations: it discloses the refusal behavior when content changes since approval, that only approved fields are stored, that retries with the same idempotency_key do not duplicate while key reuse with different details is refused, and what the response contains (contact_request_id, lifecycle_state, private status token). The annotations already declare destructive and idempotent, so the description adds real context rather than restating them, though it does not explain what 'destructive' means operationally (message goes to a third party and cannot be recalled).

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?

Front-loads the gating condition before any mechanics, then layers prerequisite, refusal, storage, and return-value sentences in a logical order. Dense but each sentence carries a distinct rule; the trailing 'listing service, not a lawyer referral service' disclaimer is the only line that serves policy rather than tool invocation.

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 17-parameter mutation tool with nested consent, an output schema, and high-consequence side effects, the description covers the approval gate, refusal paths, idempotency, and return shape. Gaps remain around how the required non-obvious fields (state, contact, preferred_contact_method) relate to the consent fields_authorized list, which the description never reconciles.

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% across 17 parameters, so the description must carry weight; it does add cross-field meaning not in the schema, tying approval_code to the specific approved version, tying idempotency_key to retry-vs-reuse semantics, and framing consent as gating the whole call. It still leaves numerous parameters (state, contact, preferred_contact_method, opposing_party_name, match_id, practice_area, intake_notice_acknowledged) unexplained in prose, relying on 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?

States a specific verb and resource ('Send my message to the lawyer I picked') and immediately distinguishes itself from the sibling preview tool by naming preview_client_message as a required prior step. The title and description together make the one-lawyer-per-call scope unmistakable against siblings like request_attorney_introduction or confirm_introduction.

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 an explicit precondition chain (person picked exactly one lawyer, saw the name, exact message, shared details and consent text, and said yes), an explicit prohibition ('Never call it on your own initiative or for several lawyers at once'), and names the required predecessor and the value to pass from it. The condition that routes to refusal (recipient or text changed since the yes) is spelled out too.

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