Handoff: File Sharing for AI Agents

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

With no annotations, the description carries the burden and does disclose real behavior: it is a mutation, it is gated ('opens stay blocked until this succeeds'), and it requires an API key. Undisclosed are permission requirements (presumably ownership), failure modes, and idempotency of repeated approvals.

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 short sentences, zero waste, with the purpose front-loaded and the consequence ('opens stay blocked') placed where it drives behavior.

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 2-parameter mutation with full schema coverage, no output schema, and no annotations, the description covers purpose, precondition, consequence, and auth — enough to call it correctly. It could be slightly stronger by pointing at get_share_status to verify the result.

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% — grant_id and api_key are already explained in the schema, including auth header preferences. The description adds no parameter-level detail beyond that, 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?

Specific verb+resource: 'Approve an owned grant that was created with requires_approval' tells the agent exactly what state transition occurs and on which object. It doesn't explicitly name deny_share as the opposite path, but the precondition makes the pairing intuitively clear.

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 condition for use is explicit: only grants created with requires_approval need approval. No exclusion or alternative is spelled out (e.g., use deny_share instead when rejecting), but the triggering context is clear enough to route correctly.

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?

With no annotations, the description carries the full burden and does meaningful work: the url/token is returned exactly once, must be saved immediately, is not re-issued by status calls, and the consumer downloads via GET. Not disclosed: defaults for max_opens/expires_in_hours, revocation behavior via revoke_share, or the approval flow beyond schema wording.

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?

Short, front-loaded sentences with zero filler: purpose first, then usage trigger, then the critical one-time-token warning, then auth. Every sentence conveys something 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?

There is no output schema, so the description correctly spends words on the return value (url + token, once) and how to consume it (GET). For a 7-parameter mutation tool with no annotations, it is close to complete; missing only default/expiry semantics and how the link is later revoked or approved.

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 every parameter including audience, audience_value, max_opens, and requires_approval is already documented in the schema; baseline is 3. The description adds only the general 'Requires your API key' auth note, no parameter-level meaning beyond 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 and resource — 'Create a controlled download link for a file you own' — which is more precise than the tool name alone. It implicitly separates itself from fetch_shared_file ('when a person or another agent should fetch the file'), but never names a sibling 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?

'Use this when a person or another agent should fetch the file' gives a clear trigger condition, plus the prerequisite 'Requires your API key.' It stops short of naming alternatives (signup, list_files, fetch_shared_file) or stating when not to use 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?

With no annotations, the description does disclose one substantive trait: "A denied grant stays blocked," which tells the agent the effect is persistent. It omits whether denial is reversible, whether it can be applied to grants you don't own, and what the call returns on success or failure.

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 short front-loaded sentences with the action first and the persistence guarantee second. The trailing "Requires your API key" is largely redundant with the api_key schema field that already explains header preferences.

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?

A two-parameter, single-action tool with full schema coverage and no output schema; the description states the action and the durability of the result, which is what an agent needs to decide to call it. Only reversibility and post-call state are left unstated, a small gap at this complexity.

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 grant_id and api_key are already documented at the schema level. The description adds no format, sourcing, or lookup guidance for grant_id, so it sits at the baseline.

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 ("Deny an owned grant") that an agent can cleanly distinguish from the sibling approve_share. Minor terminology drift between 'share' in the tool name and 'grant' in the description, but the action is unambiguous.

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?

No indication of when to deny versus approve_share, revoke_share, or get_share_status, and no stated preconditions beyond the API key. The agent must infer the approval/denial workflow from sibling names alone.

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?

No annotations are provided, so the description carries the full load and does so well: it discloses access gates (expiry, open limits, approval, agent audience), the exact inline ceiling of 1048576 bytes, what is returned on success (content_base64, plus content_text for text files), what happens on oversized files (error carrying byte size and a GET instruction), and the side effect that only a successful inline return counts as an open. That is precisely the mutation/side-effect information an agent needs.

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 purpose, then the trigger, then access rules, then the size/return contract. Every sentence carries a distinct fact (limits, return fields, error behavior, open counting) with no filler, though the density is high and would benefit from light grouping of the size/return rules.

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 no output schema and no annotations, the description fully covers the return contract (base64/text fields, size threshold), the failure path for large files, the auth modes, and the open-counting side effect. An agent can call this correctly and interpret both success and the oversized-file error without further guessing.

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 baseline is 3, but the description adds real meaning beyond the schema: it ties api_key usage to the 'agent audience' access mode and confirms url_or_token accepts either a share url or the token. It does not elaborate on the header-preferred auth detail, which the schema already covers.

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 ('Download a file') plus the accepted identifier form ('from a share url or token'), and scopes it to being handed a Handoff url and needing bytes. That reads clearly against siblings like create_share_link, list_files, and get_share_status without ambiguity.

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?

Explicit trigger: 'Use this when you were given a Handoff url and need the bytes.' It also splits the auth path by audience ('anyone_with_link needs no key. An agent audience uses your API key'), which effectively tells the caller which mode applies. It stops short of naming a sibling alternative or stating an explicit when-not-to-use case.

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?

With no annotations, the description carries the full burden: it does disclose that the grant must be owned, that results are capped at the latest 1000 entries, that refused downloads are included, and that an API key is required. It does not state whether older entries are reachable, how records are ordered beyond 'latest', or whether the caller needs ownership/team permissions beyond 'owned grant.'

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 short sentences, zero filler, with the resource scope and the 1000-entry cap front-loaded before the usage hint and auth note.

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?

There is no output schema and no annotations, so the description is the only source for return-shape information. It says what is included (access attempts, refusals) and the count cap but not what fields each attempt exposes or whether truncation at 1000 is silent — a meaningful gap for an audit 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?

Schema coverage is 100%, so both parameters are already documented in the schema, including the API key header preference and the meaning of grant_id. The description only re-asserts the API key requirement and the ownership qualifier, adding little beyond the structured fields.

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 ('Read') and resource ('latest 1000 access attempts for an owned grant'), plus a notable scope detail ('including refused downloads'). It is readily distinguishable from status/link-management siblings, though it doesn't name any of them explicitly to reinforce that distinction.

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?

'Use this to see whether a share was opened' gives a concrete triggering scenario. There are no exclusions or named alternatives (e.g., when get_share_status is preferable), so it stops short of full routing guidance.

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?

With no annotations, the description carries the full burden and does well: it discloses the auth requirement ('Requires your API key'), that the secret token is never returned (only token_prefix), and two concrete exclusions (no file download, no share URL). It stops short of stating error behavior or access-control failure modes.

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 tight sentences with zero filler: what is returned first, then the exclusions, then the auth requirement. Front-loaded and 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?

There is no output schema, and the description compensates by enumerating the returned fields, which is exactly what an agent needs to decide whether this call answers its question. Minor gap: nothing about error cases or what 'approval' values look like.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both api_key and grant_id are already fully documented in the schema. The description adds no syntax or format detail for grant_id beyond 'owned grant', 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 (read an owned grant) and enumerates exactly what is returned: token_prefix, audience, approval, expiry, revocation, open_count. It also carves out what it is not (no file download, no share URL), which implicitly separates it from fetch_shared_file, though no sibling is named 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?

'Read an owned grant' and the two exclusions imply this is the metadata-inspection path rather than the retrieval path, but the description never names an alternative or states the condition under which to prefer get_access_log, fetch_shared_file, or revoke_share. Usage is inferable rather than 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?

With no annotations, the description carries the full burden and does well: it discloses ordering, a hard 1000-item cap, that only metadata is returned (never bytes or download URLs), and that an API key is required. It omits what happens past 1000 items (truncation vs. pagination) and whether listing is scoped to owned vs. shared files.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short clauses, each earning its place: identity/ordering, intended use, return-content boundary, and auth prerequisite. Front-loaded with the core operation and no 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 no-annotation, no-output-schema, one-parameter list tool, the description covers purpose, ordering, cap, return shape, and auth — the essentials an agent needs to call it and interpret results. A brief note on what metadata fields appear or behavior at the limit would close the remaining 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% and the single api_key parameter already carries a detailed description covering header alternatives and safety advice. The description's 'Requires your API key' only confirms the auth requirement rather than adding syntax or format meaning, so 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 and resource ('List this account's files') plus scope qualifiers — newest-first ordering and a 1000-item cap — that no sibling provides. An agent can distinguish it from get_access_log, get_share_status, and fetch_shared_file immediately.

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?

'Use this to find a file_id before sharing' gives a concrete downstream purpose that implicitly routes the agent to create_share_link/save_file as the next step. There is no explicit 'do not use this for X' exclusion and no named alternative, so it falls short of a 5.

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?

With no annotations, the description carries the full load and does it well: it discloses permanence ('cannot be undone'), the concrete downstream effect ('Later downloads fail'), and the important non-effect ('does not delete the file'). It also flags the auth requirement. What's missing is whether already-issued links fail immediately or only on next fetch, and what happens when the grant is already revoked.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the verb and the destructive consequence. The closing 'Requires your API key' is largely redundant with the schema's api_key documentation, which is the only wasted line.

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 2-parameter mutation with no output schema and no annotations, the description covers the destructive semantics, side effects, and auth. Only edge cases (already-revoked grants, immediate vs. eventual link invalidation, error behavior) are absent.

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%, including a detailed api_key explanation and grant_id definition, so the schema does the heavy lifting. The description adds nothing parameter-specific beyond implying the target is an owned share; 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 and resource ('Permanently revoke an owned share') and scopes it to shares the caller owns, which helps separate it from approve_share/deny_share. It stops short of explicitly naming the nearest sibling (deny_share) or explaining the distinction, so an agent still has to infer which revocation path applies.

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 agent can infer 'use this when you want to revoke a share you own.' There is no explicit when-to-use/when-not guidance and no mention of how this differs from deny_share, which is the obvious alternative for adjacent share-state changes.

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?

With no annotations, the description carries the burden and discloses key traits: it creates a private file, does not share it, requires an API key, and returns file id plus metadata. It omits overwrite behavior, idempotency, and failure modes, but covers the main mutation and auth context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with purpose and usage. Each sentence contributes useful context: privacy, timing, return, non-sharing, and auth.

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?

The description covers purpose, prerequisite, privacy semantics, auth requirement, and return shape for a tool with no output schema. It is nearly complete, though it could say more about storage limits or overwrite behavior, which are not fully covered elsewhere.

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 the schema already documents all four parameters in detail. The description adds only high-level auth context and return information, not parameter-specific meaning beyond the schema, making the baseline 3 appropriate.

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: save a private file for this account. It also distinguishes the operation from public-sharing siblings by saying the file is private and not shared.

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: after signup, when you have bytes to store, and when you do not want a public link yet. It does not explicitly name an alternative tool or state when not to use this one, so it falls short of full routing guidance.

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?

With no annotations, the description carries the full burden and does well: it discloses the one-time key return, the absence of an auth requirement, three accepted auth header forms for later calls, and secret-handling obligations. The main gap is error behavior — agent_id is documented as "unique across Handoff" but the description never says what happens on a collision.

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 critical instruction (call first, save the key) is front-loaded and the sentences are short and purposeful. The tail-end auth-header enumeration and the "do not put it in a file you share" warning are slightly verbose for a one-time call but still earn their place as operational guidance.

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 no-annotation, no-output-schema signup tool, the description covers what is returned (api_key), how to use it afterward, and how to keep it safe, which is what an agent needs. Missing only failure-mode context such as duplicate agent_id handling or whether repeated calls mint new keys.

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% and the single parameter (agent_id) is optional, so the baseline is 3. The description adds no meaning about agent_id, and it references an "api_key" argument that does not exist in this tool's schema (additionalProperties: false), which could momentarily confuse an agent about where that parameter belongs.

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 ("Create a Handoff account") plus the salient outcome ("return an API key once"), and immediately distinguishes itself from every sibling with "Call this first, before any other tool." An agent can identify this as the bootstrap/onboarding tool without inspecting 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?

Gives explicit ordering ("Call this first, before any other tool"), an auth condition ("No Authorization header is required"), and a fallback rule ("Pass api_key only if you cannot set headers"). The one-shot nature of the key is stated, which implicitly tells the agent not to expect to re-fetch it later.

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