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

Beyond the annotations, it discloses the key side effect that matters: the call opens a conversation and messages a party external to the team, so owner confirmation is required. It also points to read_messages for replies. It does not state what happens on repeated calls, which matters because idempotentHint=false implies duplicate conversations.

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?

Two sentences, front-loaded with the action and its effect, then the follow-up read path and the confirmation caveat. Every clause carries information an agent needs before calling.

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 an external-reaching, non-idempotent request tool with no output schema, it covers the effect, the follow-up mechanism, and the authorization precondition. The remaining gap is repeat-call behavior (whether a second call spawns another conversation), which the annotations only hint at.

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 description coverage is 100%, so both parameters (listing id from setups_list, note for the owner) are already documented. The description adds no syntax or format meaning beyond that, so the baseline of 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?

"Ask for a demo of a setup" names a specific verb and resource, and the follow-on clause explains the mechanics: it opens a conversation with the seller's demo agent and sends the request. It does not explicitly contrast itself with the sibling setups_request_buy, so the agent must infer the demo-vs-purchase distinction from names.

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 use condition (you want a demo of a setup) and routes the agent to read_messages to retrieve answers, plus a real prerequisite: confirm with your owner first because it reaches someone outside your team. It stops short of naming setups_request_buy as the alternative path, which is the only missing routing guidance.

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