Xorventa

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description usefully reinforces this with 'Metadata only; it runs nothing', but adds nothing about how the lookup behaves when the action name is unknown or invalid.

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?

A single front-loaded sentence listing returned fields, closed by the most decision-relevant fact ('runs nothing'). Dense but free of filler, with no repetition of the schema or annotations.

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?

An output schema exists, so the return payload does not need describing, and the description still previews the returned fields. For a one-parameter read-only lookup the coverage is nearly sufficient; only the provenance of the 'action' value is missing.

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 0% for the single required 'action' parameter, so the description must carry the load. It only says 'One action's...', never explaining that 'action' is an identifier string, where to obtain it, or how the 200-char pattern-constrained format maps to real action names.

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?

Names a specific resource (one action) and enumerates exactly what is returned: input schema, effect, executing tool, confirmation rule, mode, owner page. The closing clause 'Metadata only; it runs nothing' sharply separates it from the mutating siblings like xora_cancel_action, though it never names xora_action_status or xora_capabilities explicitly.

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?

Usage is only implied: an agent can infer you call this to inspect an action before invoking it, and the 'runs nothing' clause signals it is safe for reconnaissance. There is no explicit when-to-use versus xora_action_status, and no statement of where valid action identifiers come from.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely useful nuance beyond them: polling this tool has no side effect on the action's execution (it never runs, retries, or changes it), which is exactly what an agent needs to know before repeated calls. It does not cover error behavior for unknown or foreign action IDs.

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 short sentences; the purpose is front-loaded ahead of the side-effect disclaimer. No filler, and every clause carries information.

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?

An output schema exists, so return values need no explanation, and the single parameter plus annotations are simple. What is present is accurate and sufficient to invoke the tool, though polling cadence or terminal-state expectations are unaddressed.

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?

With one parameter and 0% schema description coverage, the schema only supplies a UUID pattern. The description compensates partially by adding ownership semantics ('an action this connection requested'), telling the agent the ID must belong to this connection, but adds nothing about format or lookup failure behavior.

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: returns the current state of an action. The word 'state' implicitly distinguishes it from xora_action_details (which presumably returns fuller detail) and xora_cancel_action, but no sibling is named explicitly, so an agent must infer the boundary.

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?

'Reads only; it never runs, retries or changes the action' gives a clear exclusion boundary, which is useful for a status-polling tool. However it never names the alternatives (xora_action_details, xora_cancel_action) or states the conditions under which each should be chosen, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description still adds real value beyond them by disclosing the grounding sources, the suggested_actions output channel, the no-settings-mutation constraint, and the stateful thread semantics tied to workflow_id. It does not mention rate limits or answer latency, but for a read-only assistant call this is solid disclosure.

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 the core purpose and then layered with grounding, routing, scope, and statefulness in five tight sentences; each sentence carries distinct information with no filler. It is slightly longer than strictly necessary but not padded.

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 read-only assistant tool with an output schema present, the definition covers purpose, grounding, routing signal, scope limits, and conversational state, so return-value explanation is not needed. The one material omission is any guidance on context_hint, which an agent must set blind.

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 33%: only workflow_id carries a schema description. The description adds meaningful semantics for workflow_id ('pass back to continue the thread'), going beyond the schema's terse 'a workflow id this server returned earlier.' However, context_hint — an enum with seven values (general, account, assist, social, seo, persona, phone) — is never explained in either the schema or the description, leaving a real gap.

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 (ask a question) and resource (this account / Xorventa), and explicitly scopes itself as a Q&A tool that 'does not change business or account settings', which cleanly separates it from mutating siblings like xora_change_settings, xora_publish_or_send, and xora_delete.

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 clear usage context: it answers questions grounded in the help library, Business Facts, and open work, and notes that registry actions matching the request surface as suggested_actions (an implicit routing cue). It also states the thread-continuation condition ('pass back workflow_id to continue it'). It stops short of naming a specific alternative tool or an explicit when-not-to-use beyond the settings exclusion.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: the required scopes ('xorventa:prepare or xorventa:execute') and confirmation that repeat cancellation is a no-op, which sharpens the idempotency claim.

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 short sentences, front-loaded with the core action and its precondition. Every clause carries information; nothing is redundant.

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?

With an output schema present, return values need not be described, and the description covers preconditions, permissions and idempotency. It is slightly thin on how the agent obtains a valid action_id, but is otherwise adequate for a single-parameter tool.

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?

There is only one parameter and it carries no schema description (0% coverage), though the schema does supply a UUID pattern. The description clarifies that the action must belong to this connection, which is useful but does not explain the id format or where to obtain the id.

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 names a specific verb and resource ('cancel a proposed or queued action this connection requested') plus the key scope limit ('while nothing has been sent to a provider yet'), which lets an agent distinguish this from xora_delete and xora_publish_or_send. It stops short of explicitly naming a sibling, so it lands just below the top tier.

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 for use (the action must still be proposed/queued and unsent) and notes the no-op case of cancelling an already-cancelled action. It offers no explicit guidance on which alternative to pick when the action has already been sent, leaving that to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful context beyond them: pagination, required scopes, direct-vs-proposal execution mode, and the reason an action is unavailable. It stops short of describing page-size limits or the cursor contract.

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 capability list is front-loaded in a single dense sentence, with pagination as a trailing note. Every clause adds a distinct returned field, though the sentence is long enough that it reads as a list in prose form.

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 read-only catalog tool with an output schema, the definition is close to complete: it explains what an entry contains and why an action may be unusable. The only real gap is filter/pagination semantics, which the schema also leaves undocumented.

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 0%, so the description carries the full burden, yet it says only 'Paginated.' The product and effect_class filters (both enums) and the limit/cursor contract are never mentioned, leaving half the parameter surface undocumented in both the schema and the description.

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 resource (every action Xora can take, plus actions withheld by the owner) and enumerates the metadata returned for each, so an agent knows this is a capability-catalog tool. It does not, however, distinguish itself from xora_action_details or xora_action_status, which are the nearest siblings.

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?

Usage is only implied: the enumeration of scopes, effect classes, and 'whether this connection can use it now' signals a discovery step before acting, but there is no explicit when-to-use statement, no exclusion, and no pointer to xora_action_details for deeper inspection.

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

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

Goes well beyond the annotations by disclosing the auth model (xorventa:manage / xorventa:execute / xorventa:prepare proposal flow), the upload-side effects for the social media actions including how image_url and file_base64 with mime_type are validated, and the retry semantics tied to client_request_id. These are meaningful behavioral traits an agent cannot derive from readOnlyHint/destructiveHint/idempotentHint alone.

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?

A single paragraph but front-loaded with the purpose and capability scope before the permission and upload caveats. Dense and information-rich rather than padded, though the run-on sentences about the prepare/execute proposal path and the enumerated action family could be tightened.

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 4-parameter dispatcher with nested free-form arguments and an output schema present, the description covers everything an agent needs: what runs, under which permissions, what happens on the execute/prepare fork, what is refused, upload attachment rules, and idempotency. Return-value details are correctly left to the output schema.

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%, and the description adds real meaning on top: 'action' is the registry name of the action to run, 'client_request_id' is what makes a repeat call return the recorded action instead of rerunning it, and the social-media actions take image_url or file_base64/mime_type. It doesn't explain the workflow_id parameter at all, which is the remaining gap.

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 settings action from Xorventa's own account API, by name with its arguments') and enumerates the domain it covers (chat window, Business Facts, knowledge sources, assistant, phone, mailbox, SEO settings). It also explicitly carves out what it is not — reads, publishing, sending, deleting — which is exactly what the sibling tools xora_read, xora_publish_or_send and xora_delete do.

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 clear preconditions (connection must hold xorventa:manage and the owner must allow Xora to change settings; certain settings also need xorventa:execute or become a xorventa:prepare proposal) and an explicit exclusion list that routes reads/publishing/sending/deleting elsewhere. It stops short of naming the alternative tools, so the agent must infer the routing rather than being handed it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true; the description goes further by explaining the mechanism (a repeated client_request_id returns the recorded action instead of re-running) and the authorization/proposal model. It does not say whether deletions are permanent or recoverable, or what cascade effects hit dependent objects like connections, which is the remaining gap for a destructive tool.

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?

Five sentences with no filler and the core purpose front-loaded in the first clause. It is dense but each sentence contributes a distinct fact (scope, modes, refusal, idempotency); the long enumeration in sentence one slightly crowds the opening.

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?

An output schema exists, so return values need no explanation, and the description covers the authorization model, refusal behavior, and idempotency for a destructive, open-world action. The only material omission is `workflow_id` and any statement about permanence or side effects of the deletion.

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 meaning; the description adds that `action` is a registry name for a delete action paired with that action's own `arguments`, and reinforces the idempotency contract of `client_request_id`. `workflow_id` is never mentioned in the description and remains undocumented beyond its schema type.

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?

Names a specific verb (delete) plus the exact resource categories it removes (drafts, records, knowledge sources, reports, connections, published posts), and explicitly bounds scope with "It refuses every other kind of action." An agent can distinguish this from xora_read, xora_publish_or_send, or xora_cancel_action without opening any schema.

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?

Explains the mode-dependent routing: with xorventa:execute it runs under owner switches, with xorventa:prepare and no execute it becomes a proposal confirmed at owner_confirmation_url. That is real when-to-use context, but it never names a sibling alternative (e.g. when to prefer xora_cancel_action or xora_read) or states prerequisites for obtaining those scopes.

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

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

Beyond the annotations (destructiveHint, idempotentHint, openWorldHint), the description discloses the prepare-vs-execute proposal flow and the owner_confirmation_url handoff, the media handling path (image_url fetched over https vs file_base64 with mime_type), and how idempotency actually behaves on a repeated client_request_id. This is substantial context that the 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?

The core purpose and the execution-mode behavior are front-loaded, and the later sentences on media and idempotency each add non-redundant information. The single dense paragraph is slightly heavy, but no sentence is filler.

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 dispatch tool it covers the important behaviors (modes, confirmation, media, idempotency), and the existence of an output schema removes the need to describe return values. The only real gap is the unexplained workflow_id and the fact that valid action names live in an external registry rather than being listed.

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 baseline is 3, but the description adds real meaning: it specifies that image_url and file_base64+mime_type travel inside the 'arguments' object for the social-media actions, which the schema only describes vaguely as 'the action's own arguments'. The workflow_id parameter is left unexplained, keeping it from a 5.

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 names a specific verb (runs one publishing/sending action), the resource (Xorventa's account API), and enumerates the exact action families it covers: social posts and replies, email replies, notifying appointment changes, and website changes. It further distinguishes itself from siblings with the exclusion 'It refuses every other kind of action', letting an agent separate this from xora_read, xora_delete, or xora_upload_* without opening a schema.

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 the key conditional: with xorventa:execute it runs within the owner's switches, while with xorventa:prepare and no execute it becomes a proposal confirmed at owner_confirmation_url. The 'refuses every other kind of action' line implies routing to other tools for non-publish operations. However, no sibling is named as an explicit alternative for those other action kinds, so the guidance is strong but not fully exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real value: the server-side refusal of mutating actions and the replay semantics keyed to client_request_id (a retry returns the recorded action rather than rerunning it).

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?

Three sentences, front-loaded with what the tool does and ending with the idempotency contract. The middle sentence is a long enumeration, but every clause carries information and nothing is padding.

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?

An output schema exists, so return values need no prose. For a generic action dispatcher the description covers behavior, scope and idempotency adequately; the only meaningful omission is how an agent should discover or validate the action names it must pass.

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% and the description mostly restates the schema's framing of "action by name with its arguments." It adds no guidance on what valid registry action names look like or where to obtain them, which is the central ambiguity for this dispatcher-style tool.

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 (runs/returns) and resource (one read-only action from Xorventa's account API), and enumerates the data domains covered (chat windows, Business Facts, settings, drafts, posts, SEO audits, activity). This clearly distinguishes it from siblings like xora_action_status and xora_action_details.

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 a clear when-to-use condition (read-only data retrieval) and an explicit exclusion ("refuses any action that changes something"), which routes write intents to siblings like xora_publish_or_send, xora_delete or xora_change_settings. It does not, however, name those alternatives or point to xora_capabilities for discovering valid action names.

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

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

Annotations declare openWorld and non-idempotent, but the description goes well beyond them: it discloses SSRF protections (private, loopback, link-local and non-https refused, redirects rechecked), that the staging is one-time and expires after ten minutes, and what upload_reference is for. This is exactly the extra behavioral context annotations 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?

Three sentences, front-loaded with the core action and then the constraints, with little waste. The sentences are dense but every clause carries distinct information; only minor tightening is possible.

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?

An output schema exists so return values need not be explained, and the description covers security constraints, staging semantics, single-use/expiry and how the resulting reference is consumed. Nothing an agent needs to call this correctly is missing.

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 100%, so the schema already documents url, action and filename, and the baseline would be 3. The description adds value by tying the action parameter to 'an action that takes a file' and by explaining the upload_reference → upload_id linkage that the action expects, clarifying the parameter contract across tools.

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: fetches a file from a public https address and stages it as a one-time upload for an action that takes a file. This is clearly distinguishable from the upload_prepare/upload_request/upload_status siblings and an agent can tell what it does without opening the schema.

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?

The description implies the alternative ('after the same type and size checks a direct upload meets') and the workflow ('an action that takes a file'), so usage is implied. However it never explicitly names a sibling (e.g. xora_upload_prepare) or states when to prefer one upload route over another, leaving the routing decision inferred.

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

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

Annotations only give the generic hint set (not read-only, not idempotent, not destructive). The description supplies the operationally critical facts: the upload_url accepts exactly one HTTPS PUT of exactly the declared bytes, carries its own single-use credential so no Authorization header is required, and expires after ten minutes, and that the server never reads a local path.

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 sentences, each load-bearing, with the reservation purpose front-loaded and the return/credential mechanics following. Dense but not padded; a little more length than strictly required for the credential and expiry details, which are nonetheless valuable.

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?

Given an output schema exists, the description correctly does not restate every return field, yet it still explains the two returned URLs and required_headers in behavioral terms. For a five-parameter, non-idempotent mutation tool this leaves no material gap for an agent to call it correctly.

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 0%, so the description must carry the burden, and it does: it explains that action identifies the target that takes a file, and that the declared mime_type, byte_size and sha256 are checked against that action's limits. filename and the exact-match PUT semantics are covered too, though format details for each field are left to the schema patterns.

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: it reserves a one-time upload slot for a named action, gated on type/size/SHA-256 validation. That framing separates it from sibling tools like xora_upload_from_url, xora_upload_request and xora_upload_status without the reader needing to open any schema.

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 clear context for when to call it (an action that takes a file, where the caller holds the bytes) and names concrete alternatives: owner_upload_url for handing the choice to the owner, and passing an image to the action directly by address or base64 for social posts. It stops short of naming sibling tools explicitly, but the conditions for choosing each route are stated.

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

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

Adds meaningful behavior beyond the annotations: the file is checked against the action's type/size limits, staged as a one-time upload, and the slot expires after ten minutes unused. It also states the call 'changes nothing else,' which contextualizes the non-idempotent hint. Auth requirements and rate limits remain undisclosed.

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 the core action and reasonably sized, but the back half is dense and slightly confusing: 'the owner chooses the file there' in the picker versus the return of a Xorventa page where the owner chooses the file 'instead' reads as two competing mechanisms.

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?

An output schema exists, so return values needn't be explained, and the description covers the interaction flow, staging, and slot TTL adequately. Only the missing when-to-use guidance against sibling upload tools leaves a small gap.

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 100%, so the schema already documents note, action, post_id and campaign_id in detail. The description references the action's type/size limits but adds no syntax or format 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+resource: reserving an upload slot and showing the owner a file picker for an action that takes a file. The upload/staging flow distinguishes it from a generic upload, though it never names a sibling (e.g. xora_upload_from_url, xora_upload_prepare) to sharpen differentiation.

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?

Usage is only implied through 'for an action that takes a file' and the post/campaign context. There is no explicit when-to-use-vs-alternative guidance for choosing this over xora_upload_from_url or xora_upload_prepare, so the agent must infer the routing.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower; the description usefully adds the validation semantics (size, hash, type checks) and explains what 'ready' means. It stops short of describing polling behavior or error/failure states, so not a 5.

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, zero padding, with the core meaning (arrival + checks) front-loaded and the downstream usage (upload_reference feeding an upload_id argument) placed second. Every clause earns its place.

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?

An output schema exists so return shapes need not be re-explained, and the description still adds the key semantic link between upload_reference and download-side upload_id. The only real omission is the origin/lifecycle of the input upload_id relative to upload_prepare.

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 0% for the single upload_id parameter, and the description never explains where that id comes from or its expected form. It does clarify the related upload_reference value, but that is an output, not the input parameter, so compensation for the coverage gap is partial.

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 resource (a prepared upload) and what the tool reports (whether it arrived and passed size/hash/type checks). It connects conceptually to upload_prepare via 'prepared upload' but never names a sibling, so differentiation is implied rather than explicit.

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?

Usage is only implied: an agent infers it should be called after preparing an upload. There is no explicit when-to-use guidance, no statement of what to do on failure, and no routing against the other upload siblings (prepare/request/from_url).

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

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

Annotations already establish readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so 'Reads only' adds nothing. Where the description does earn credit is the follow_up semantics: waiting items arrive paired with an offering question and the concrete read action that lists each one, which tells the agent the tool hands back actionable next steps rather than inert data.

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, no filler, with the returned content front-loaded before the follow_up mechanics. The second sentence is dense but every clause conveys distinct information about how follow_up is shaped.

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 zero-parameter read with an output schema and full annotation coverage, the agent needs little else. The description covers the content categories and the follow_up interaction pattern; the only shortfall is the absence of any routing guidance against sibling read tools.

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?

The tool takes zero parameters, which sets the baseline at 4. The description correctly adds no parameter discussion because there is nothing to define.

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 enumerates exactly what the tool surfaces: account products, unfinished setup tasks, items awaiting the owner's decision, and page links. That is a specific, recognizable read of account status. It does not, however, distinguish itself from siblings like xora_read or xora_action_status, so an agent must infer the boundary.

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?

There is no explicit statement of when to call this versus the alternatives (xora_read, xora_action_status, xora_capabilities). The mention that follow_up items 'this connection can work through in the conversation' hints at a follow-on workflow but never says when the agent should reach for this tool.

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