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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive write. The description adds two genuinely useful facts beyond them: the post is publicly live immediately and is attributed with a 'Posted via AI agent' label. It still omits auth requirements (agent_key vs legacy hostname/publish_key) and whether a post can be edited or retracted after going live.

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?

Two tight sentences with the core action front-loaded and the behavioral caveat second; every sentence earns its place. The brevity is close to under-specification, but the dimension is about waste and ordering, and there is none.

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 mutation tool with a deep nested schema, 50% description coverage, no output schema, and an open-world publish side effect, the description is far too thin. An agent would need to reverse-engineer required fields, valid enum values, and which credential parameter to supply from the schema alone, with no guidance on consequences of an incorrect post.

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 50%, and the description says nothing about any parameter, including the required nested `request` object with twelve fields and the large enum vocabularies for categories, industries, deal_types, and request_type. The two legacy-vs-new auth parameters (agent_key vs hostname/publish_key) are only explained in the schema, and buyer_role/contact_email are undocumented entirely, so the description does not compensate for the coverage gap.

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?

"Post a buyer request" gives a specific verb (post) plus resource (buyer request) that matches the tool name and distinguishes it from read-side siblings like get_buyer_request or search_buyer_requests. It does not, however, distinguish it from create_listing, the other write tool in the family, so an agent cannot tell from the description alone which creation tool applies.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of the alternative create_listing. The only implicit signal is the name itself; an agent must infer that this is for demand-side (buyer) posts rather than supply-side listings.

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