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

The description discloses substantial behavioral traits beyond the minimal annotations: credit consumption, credit refund policy with the prohibited/spam exception, AI moderation with 'pending' status, ACTIVE_LISTING_LIMIT_REACHED error with pay_url, and the AUTH_REQUIRED error with authorize_url. This is rich side-effect and failure-mode disclosure. No contradiction with annotations — readOnlyHint false matches the write operation, idempotentHint false matches credit consumption.

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 description is long (7 sentences) but every sentence carries distinct, non-redundant information: scope, location constraint, credit consumption, limits, moderation, refund policy, photo workflow, and auth requirement. Critical constraints are front-loaded (purpose, location, credits) before the workflow details. It is dense but efficient, with no filler — the length is justified by the volume of behavioral content.

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 complex tool (9 params, 6 required, nested location object, 2 enums), the description is remarkably complete. It covers prerequisites (entitlements check, image upload), constraints (coordinate location, credit/slot limits), error handling with actionable recovery steps, moderation behavior, and auth requirements. An output schema exists to document return values, so nothing an agent needs to call this correctly is missing.

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 low at 33%, so the description must compensate. It adds genuine value on the images parameter (keys must come from request_image_upload) and reinforces the location constraint (coordinates required, geocode first). The schema already richly documents role (supply/demand pairs) and currency. However, several parameters (price, title, details, description) receive no added meaning in the description beyond the schema, so compensation is partial.

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 uses a specific verb ('Publish') with a clear resource ('listing') and defines the scope precisely ('across any of the 4 verticals and 12 roles'). It clearly differentiates from sibling tools like update_listing, delete_listing, and set_listing_status by signaling creation of a new listing rather than modification or lifecycle management.

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?

The description gives explicit sequencing guidance: call get_entitlements to check balance/slots before publishing, call request_image_upload for each photo before invoking this tool, and surface 'Connect with Teppek' then retry on AUTH_REQUIRED. It names sibling tools and their role in the workflow. It lacks an explicit 'when not to use' contrast with update_listing, though the create/update name distinction makes this largely self-evident.

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