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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write nature is known. The description adds genuinely non-structured context: that it is a feedback submission, that case details must be excluded, the deprecation window, and the business framing (listing service, no paid placement). It does not explain that non-idempotent retries may duplicate feedback, which is the one behavior an agent could get wrong.

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?

The deprecation pointer and replacement are correctly front-loaded, and the rating enumeration is compact. However, the closing two sentences about being a listing service and no paid placement read as legal boilerplate that does not help an agent decide or invoke, diluting an otherwise short definition.

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?

An output schema exists, so return values need no explanation, but the description is thin for a 12-parameter mutation with zero required fields. The critical unknown, whether match_id, referral_id or status_token is needed to attribute feedback, is unaddressed, and the three indistinguishable satisfaction fields are left to guesswork.

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?

With 12 parameters and only 8% schema description coverage, the description must carry the load, and it only covers the rating fields and 'retained' at a high level. It never distinguishes the three satisfaction fields (match, process, attorney), nor explains match_id, referral_id or status_token, leaving it unclear which identifier a caller must supply when nothing is marked required.

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 states plainly that this is the older name of submit_listing_feedback and summarizes the payload as optional 1-5 ratings on listing usefulness, responsiveness, pricing/availability accuracy, satisfaction and whether the lawyer was hired. That is a specific verb+resource, and it is distinguishable from siblings like submit_listing_feedback or get_referral_status. It leans on the sibling name to carry the core purpose rather than stating it directly.

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?

It gives an explicit routing instruction: use submit_listing_feedback instead, and states the alias is kept only until 2026-12-15. That is precisely the when/when-not guidance an agent needs, with the preferred alternative named and a hard cutoff date.

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