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

Annotations already flag destructive/idempotent/open-world, but the description adds substantive behavior: the execute-vs-prepare switch, outright refusal of other action kinds, the fact that image_url is a public https address the server fetches, and the concrete idempotency contract ('a repeated call with the same client_request_id returns the recorded action and does not run it again'). This goes well beyond the structured 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?

Front-loaded with purpose, then mode semantics, then media and idempotency, all in four dense sentences with little waste. It is on the long side and 'checked like any upload' is a slightly vague aside, but every sentence carries information an agent needs.

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 mutation tool with an output schema, the description covers mode selection, refusal scope, media handling and retry semantics, which is most of what an agent needs. It does not touch permission/authentication requirements or failure behavior, which are the remaining gaps.

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 75%, so the schema carries most parameter documentation. The description still adds meaning: `action` is the registry name of one of the enumerated action types, media is supplied via image_url or file_base64 plus mime_type and 'checked like any upload', and client_request_id is caller-generated for safe retries. It clarifies the nested `arguments` object only by reference to the action's own 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?

States a specific verb and resource ('Runs one publishing or sending action from Xorventa's own account API') and enumerates the covered action families: social posts/replies, email replies, appointment notifications, website changes. 'It refuses every other kind of action' implicitly carves it out from siblings like xora_read, xora_delete and xora_change_settings, so an agent can route without opening schemas.

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 explicit mode conditions: with xorventa:execute it runs inside the owner's switches; with xorventa:prepare and no execute it becomes a proposal confirmed at owner_confirmation_url. That is clear when-to-use context, but it does not name the sibling tools an agent should use instead for the excluded action kinds.

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