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

Beyond the annotations, the description discloses rich behavioral details: the question is stored and the seller is notified via a question.asked event, answers come back as question.answered or via getQuestions, visibility modes are explained, errors are enumerated, and a 60-per-day rate limit is stated. It also flags that the question field is untrusted, adding meaningful security context.

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 but every sentence earns its place: usage guidance, behavior, error conditions, reply shape, rate limit, and security note are all packed in without redundancy. Critical context appears early, with the purpose and primary alternative stated first.

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?

With no output schema, the description carefully explains the reply shape (question_id, asker, answer: null). It also covers auth needs, side effects, events, error cases, rate limits, and visibility semantics. Combined with the schema's explanation of idempotency, an agent has everything needed to call this tool correctly.

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 already high (75%), so the baseline is 3, but the description adds value beyond the schema: it explains the real-world effect of visibility choices and marks the question field as the only free-text input and as _untrusted. It does not add detail for listing_id or idempotency_key, but those are adequately covered by 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?

The description opens with a specific verb and resource: 'Ask the seller of a listing a question before buying.' It clearly distinguishes this tool from siblings like answer and getQuestions by describing the ask flow and where the answer can be retrieved. An agent can immediately understand what the tool does and what it is not.

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 guidance: read getQuestions first to check for an existing public answer, and ask before buying. It also states when the call will be refused (own listing, paused listing, missing/deleted listing), which acts as a clear when-not-to-use guide. This is strong, actionable usage context.

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