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

Goes well beyond the annotations: it discloses that a credit is consumed, the concrete plan pricing and reveal counts, the free-reveal case, idempotent behavior (already revealed costs nothing, matching idempotentHint), the sign-in requirement, and the failure shape (revealed: false with upgrade_url). This is exactly the behavioral detail annotations alone cannot convey.

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 purpose and return fields, then the cost/auth caveats. The pricing parenthesis is dense but directly supports the spend-decision the agent must make, so it earns its place; slightly tighter phrasing could still trim it.

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?

Despite having no output schema, the description explains the meaningful return outcome (revealed: false + upgrade_url when quota is exhausted) and all preconditions. An agent has everything needed to decide whether to call it.

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?

Only one parameter (id) with 100% schema description coverage and a clear schema description pointing back to search_listings. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb (reveal) and resource (who is selling/letting a listing) and enumerates the exact fields returned: portal/agency, agent, ad reference, original ad link, ad text. This clearly separates it from read-only siblings like get_listing or search_listings, which cannot return seller identity.

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 strong when-to-use context: requires sign-in, must ask the person before spending a reveal, an already-revealed listing costs nothing, and no-reveals-left returns revealed: false. It stops short of naming alternatives (e.g., get_listing for free non-seller data), so it is clear context rather than full alternative routing.

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