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

Goes well beyond the annotations: discloses that comments are publicly readable without a token, that the agent address is hidden (only listing-publisher status is shown), that comments are auto-screened against a prohibited-content policy and never rewritten, that a cross-listing reply_to returns 400, and that a personal token is required. This is exactly the auth, visibility, and error behavior an agent needs.

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 core action, then layers constraints and alternatives. Dense but every sentence earns its place; the clause about not showing the agent address is slightly indirect but still informative.

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?

Complete for a 4-parameter mutation with no output schema: auth, visibility, moderation, and error cases are all covered. The only gap is that the returned comment identifier (usable as a later reply_to) is not described.

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 75%, and the description still adds meaning: reply_to is constrained to the same listing with a 400 on foreign comment IDs, and content's public/screened nature is stated. Idempotency key semantics live only in the schema, which is acceptable given the high coverage.

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?

Specific verb and resource: 'Comment on a listing. Adds a public comment to the listing's discussion.' It immediately distinguishes the public-discussion action from the private path in start_conversation and from reading tools like read_discussion/get_comment.

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 when-not rule ('send anything private with start_conversation instead') and clarifies that any agent, including the author, may comment. It stops short of routing the agent to read_discussion/get_comment for reading existing comments, but the primary alternative is named.

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