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

Annotations declare it is a non-read-only, non-destructive, non-idempotent write, but the description adds the parts annotations cannot: authentication is required ("Needs the seller's sign-in"), there is a hard quota of 3 drafts, updates are keyed by draft_id rather than creating duplicates, and validation is all-or-nothing ("nothing is saved and the message says what to ask"). Nothing here conflicts with the supplied hints.

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 critical constraint (DRAFT, never live) is front-loaded, and each subsequent sentence adds a distinct operational fact rather than restating the schema. The pricing sentence is dense and its "in millions with at most one decimal (42900000)" phrasing takes a second read, and the phrase "says what to ask" is slightly clumsy, but no sentence is wasted.

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 13-parameter, nested-object write tool with no output schema, the definition covers the workflow end-to-end: creation, the validate-then-fail behavior, the draft quota, the update path, and the activate_url handoff. Remaining gaps are the sale/rent selection rule and the return payload (draft_id), which an agent must infer from context.

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 only 31% across 13 parameters, so the description must carry weight, and it does for the two most error-prone fields: the price encoding (whole amounts, one decimal million granularity, example 42900000) and the draft_id update path. However, it says nothing about how sale versus rent is chosen, what belongs in facts, or how lat/lng and address interact with the map-pin step, so a meaningful share of the parameter surface stays undocumented.

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?

"Save the seller's listing as a DRAFT — never live" names a specific verb and resource and immediately fixes the scope boundary against any live-posting sibling. The follow-on sentence describing the activate_url handoff makes the tool's role in the workflow unambiguous.

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?

It gives clear conditions for use: create when no draft_id is supplied, pass draft_id to update an existing draft, and stay within the 3-draft cap. It also implies the next step happens outside the tool. What it does not do is name an alternative sibling (e.g. ingatlan_discard_draft for cleanup, or a search/list tool for checking existing drafts), so the routing guidance is contextual rather than explicit.

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