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?

Annotations already declare readOnly=false, idempotent=true, destructive=false, openWorld=true; the description adds real value beyond them: the permission model (manage/execute/prepare-proposal), the refusal set, and the retry semantics ('a repeated call with the same client_request_id returns the recorded action and does not run it again'). It also flags that upload_social_media and add_campaign_draft take media in the same call and how it is checked. The one gap is that it does not say how to discover valid action names or what a successful response looks like beyond the dedupe case.

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, then auth, refusals, media, and idempotency in a logical order. It is a dense single paragraph but every sentence carries distinct information; only the long domain enumeration runs slightly long for a dispatcher.

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-value detail is not needed, and annotations cover the safety profile. The description supplies the permission gating, refusal scope, media handling and idempotency that a dispatcher's caller needs. It stops short of pointing to xora_action_details or xora_capabilities for enumerating valid action names, which would fully close the loop for an open-world registry.

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 of the load (action registry name, arguments passthrough, workflow_id, client_request_id). The description adds meaning the schema cannot: that 'arguments' are action-specific per each action's own input schema, the media parameters required only by two particular actions, and the replay semantics of client_request_id. This goes beyond restating the 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+resource ('runs one settings action from Xorventa's own account API, by name with its arguments') and enumerates the domains it spans (chat window, Business Facts, knowledge sources, assistant, phone, mailbox, SEO, drafts). It explicitly refuses reads, publishing, sending and deleting, which cleanly separates it from xora_read, xora_publish_or_send and xora_delete 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?

Gives concrete when-to-use conditions (connection holds xorventa:manage and the owner has allowed setting changes) and when-not (refuses reads/publishing/sending/deleting). It also names the escalation paths: xorventa:execute for always-confirm settings, or a proposal confirmed via xorventa:prepare — routing an agent to the right behavior on the ambiguous cases.

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?

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.

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?

Goes well beyond the annotations (readOnly=false, openWorld=true, non-idempotent, non-destructive) by disclosing SSRF protections — private, loopback and link-local addresses plus non-https addresses and every redirect to one are refused — along with type/size checks, single-use semantics, and a ten-minute expiry on the staged reference.

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 dense sentences, front-loaded with the purpose before the refusal rules and the output contract. Nothing is padded; the expiry and single-use facts in the final sentence are operationally necessary.

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 still supplies the one thing that matters operationally — how upload_reference is consumed and how long it lives. With rich annotations and full schema coverage, an agent has everything needed to call this 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 100%, so url, action and filename are already fully documented in the schema, which sets the baseline at 3. The description adds the useful flow detail that the returned upload_reference is passed as the upload_id argument, but contributes no additional per-parameter syntax or constraint detail.

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. The phrase 'after the same type and size checks a direct upload meets' implicitly contrasts it with the direct-upload siblings, but no sibling tool is named explicitly, so differentiation is inferential rather than stated.

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 establishes the precondition that the target action must take a file and explains what to do once state is 'ready', which implies usage. However it never says when to choose this over xora_upload_prepare or xora_upload_request, nor names any alternative, so the routing guidance remains implied rather than explicit.

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.