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

Beyond the annotations it discloses two non-obvious behaviors: creation is retry-safe, and the listing remains unverified until verification completes (with an instruction to tell the user). Note the mild tension with idempotentHint=false — 'retry-safe' is not the same claim as idempotent, so this is clarification rather than a contradiction, but the agent could still wonder whether a retry yields the same listing.

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?

Four short sentences, each carrying distinct information: the action, the prerequisite, the duplicate-confirmation gate, and the post-creation state. The critical gating rule is front-loaded right after the action statement, with no restatement of the name or title.

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 destructive, open-world, non-idempotent creation tool with a nested listing object and no output schema, the description covers the lifecycle (unverified until verification) and the safety gate. It does not say what identifies the created listing on return or what happens if a possible duplicate turns out to exist, leaving a small gap for the agent.

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 67%, and the description compensates where it matters most: confirmed_not_duplicate has no schema description at all, and the description supplies its exact semantics and safety condition. It also ties site_id to linking the listing, though setup_id and connection_id are left entirely to their schema blurbs.

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 states a specific verb and resource ('Create the NEW Google listing') plus the side effect ('link it to this site'), and it names the prerequisite sibling prepare_google_listing so the agent can place this call in the Google-listing workflow rather than confusing it with prepare_google_change or choose_google_location.

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 a clear precondition ('after prepare_google_listing') and an explicit gating rule for confirmed_not_duplicate=true only after the owner confirmed none of the possible matches is theirs, which is exactly the when-to-use guidance an agent needs. It doesn't explicitly rule out alternative paths such as re-preparing a change or choosing an existing location, so it stops short of full when-not coverage.

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