Stream Vessel

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is partly covered. The description still adds real behavioral value beyond them: the billing consequence of leaving parts in place, the guarantee that existing objects are untouched, and the explicit idempotency semantics ('already gone counts as success'). Auth or permission requirements are not mentioned.

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, each carrying a distinct point (destructive scope, non-interference with objects, idempotency), with the primary action front-loaded. Phrasing is slightly terse and idiomatic 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, idempotent operation with no output schema, the description covers scope, billing side effects, and idempotency, and annotations carry the safety profile. Return behavior and permission prerequisites are unaddressed, but these are minor for this tool class.

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%, with all four required parameters (connectionId, bucket, key, uploadId) documented in the schema itself. The description adds no parameter-level detail such as formats or the source of uploadId, 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?

The description states a specific verb and resource: it discards an upload plus its already-sent parts. It also distinguishes itself from object-deletion siblings by noting it 'cannot touch an object that already exists at the key,' so an agent can tell it apart from delete_object. It stops short of naming siblings such as abort_unfinished_uploads or complete_multipart_upload.

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 scope note ('cannot touch an object that already exists at the key') implicitly tells the agent this is for discarding in-progress uploads rather than deleting objects, which is a weak when-not signal. However, no alternative is named and no explicit condition for choosing this over abort_unfinished_uploads or complete_multipart_upload is given.

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 annotations already declaring destructiveHint=true and idempotentHint=false, the description adds substantial context beyond them: parts are billed until discarded, uploads newer than 24 hours are refused rather than discarded unless includeRecent is true, each entry gets its own outcome, and a non-open key is reported as failed and left untouched so a wrong id cannot read as success. It also states it cannot touch an already-existing object.

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 dense sentences, front-loaded with the action and then the constraints, all of which earn their place. Slightly long, but there is no filler or repetition.

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 batch tool with no output schema, the description covers the important gaps: billing implications, the recency guard and its override, and per-entry success/failure reporting. Nothing an agent needs to call it safely and interpret outcomes 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% and both includeRecent and the uploads provenance are already documented in the schema, so the baseline is 3. The description goes further by explaining the rationale behind the 24-hour gate ('it may be a transfer still running') and the per-entry failure semantics, which the schema does not convey.

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 opens with a specific verb and resource ('Discards a list of unfinished uploads and the parts each holds') and the plural 'list of' distinguishes it from the singular sibling abort_multipart_upload. An agent can tell what it does and that it is the batch variant 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?

It gives a clear prerequisite workflow: name entries with the key and uploadId that list_multipart_uploads reported, and show that list to the user first. It also flags the 24-hour refusal and the includeRecent override. It stops short of naming abort_multipart_upload as the single-upload alternative, so no explicit when-not 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?

Goes well beyond the annotations: it discloses the exact probe mechanics (unsigned listing plus unsigned read of one existing object, no credentials), the three-valued outcome and the explicit warning that 'unknown' is not safe, the network side effect (one request per reading to the bucket's own host on the caller's behalf), and the auth/ownership constraint. The readOnly/no-state-change claim is consistent with readOnlyHint and destructiveHint=false.

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-loads what the tool does before the caveats, and every sentence carries information (mechanics, return semantics, side effects, ownership). It is dense and long-ish, but nothing is filler; a slightly tighter grouping of the caveats could improve scanability.

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 carries the return-value burden and does so fully by defining public/private/unknown and their safe interpretation. Combined with the side-effect and ownership disclosures, an agent has everything needed to invoke and interpret 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 coverage is 100%, so both parameters are already documented, but the description adds real semantics for connectionId: shared connections silently return the same not-found as a wrong id, which the schema does not convey. That is meaningful meaning beyond the structured field.

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 concrete verb and resource ('probes one bucket the way an anonymous stranger would') and immediately distinguishes itself from every sibling, none of which perform an anonymous exposure probe. An agent can pick this tool over list_buckets or get_object_metadata without opening either 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 a clear applicability condition (owner-only; works only for a connection this account created, never a shared one) and even tells the caller how a shared-connection id will fail. It stops short of naming alternative tools for adjacent questions, but no sibling overlaps meaningfully, so the context is sufficient.

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 and idempotentHint=false, so the safety profile is partly structured. The description still earns credit by adding genuinely new behavior: the replacement is irreversible, and undersized parts are rejected at completion rather than at upload time. Minor gap: it presents the key replacement as unconditional, while the schema gates it behind an 'overwrite' flag.

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 tight sentences, each carrying distinct payload: action, required inputs, destructive lifecycle effect, and size validation. The most consequential fact (object appears / irreplaceable loss) is front-loaded after the action statement.

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?

No output schema exists, so the description is not obliged to describe return values, and the destructive annotation covers safety. It covers the lifecycle well, but omits what state remains on failure (parts persist until abort) and the interaction with the 'overwrite' parameter.

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 baseline is 3. The description adds real provenance for one parameter (the ETag must come from the part's PUT response), but says nothing about overwrite, uploadId source, or connectionId, and its unconditional-replacement wording partially conflicts with the 'overwrite' boolean.

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: 'Assembles the uploaded parts into the object,' which distinguishes it immediately from start_multipart_upload, abort_multipart_upload, and write_object. An agent can identify this as the terminal finalization step 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?

Clear context: this is the step after all parts are PUT, and it requires each part's number and returned ETag. However, it gives no explicit alternative routing (e.g., what to call instead if a part is missing or the upload should be abandoned).

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 destructiveHint=true and idempotentHint=false, but the description adds the specifics an agent actually needs: the exact failure condition (existing destination key), the flag that changes it, and the irreversibility of overwriting. That is genuine added behavioral context rather than a restatement of the 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?

Two sentences, zero waste, with the copy-vs-move distinction front-loaded and the failure/overwrite semantics following. 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?

For a mutation tool with no output schema, the description covers the key risk profile: side effects, failure mode, and irreversibility. It omits any hint about the response (e.g., whether the new object's identity is returned) and any cross-bucket constraints, which is a minor 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 baseline is 3, but the description adds meaning the schema's neutral wording omits: the consequence of overwrite (irreversible replacement), not just its mechanical effect. The other five path/connection parameters are adequately covered by the schema and need no further elaboration.

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 (copies an object) and immediately distinguishes itself from the sibling move_object by noting the source is left in place. An agent can select this over move_object or write_object 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?

Gives a clear precondition for use: it fails when the destination key exists unless overwrite is true, which tells the agent when the plain call is unsafe. It does not explicitly name alternatives (e.g., move_object when the source should be removed), so routing guidance is strong but not complete.

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 destructiveHint=true/idempotentHint=false, and the description adds non-obvious behavior beyond them: the trailing-slash requirement, the destination-nonempty refusal, the one-object-per-request design, the smaller ceiling relative to delete_prefix, and early-stopping. It doesn't describe partial-copy state on early stop, which is the main residual gap.

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 dense sentences, front-loaded with the core action and layout semantics. The trailing phrase 'says so when it stops early' is slightly colloquial but carries a useful operational hint, so little is wasted.

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, no-output-schema mutation tool with full annotation coverage, the description covers the critical calling constraints (slash rules, overwrite, per-request copy, ceiling). What's missing is failure semantics—whether already-copied objects remain if it stops early—which an agent would want before invoking.

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 constraint meaning: prefixes must end in '/', overwrite governs the nonempty-destination case, and destination layout is preserved. This explains *why* the parameters matter rather than repeating their definitions.

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 ('Copies every object under a prefix to another prefix') and explicitly describes scope ('keeping the layout below it'), which cleanly separates it from the single-object copy_object and the move_prefix sibling.

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-not condition ('Refuses to write into a destination that already holds objects unless overwrite is true') and comparative context against delete_prefix's ceiling. It stops short of naming the obvious alternatives (copy_object, move_prefix) or telling the agent when to prefer them, so it's clear context without explicit exclusions.

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 the safety profile is covered. The description adds that the link is short-lived, which is useful, but it does not mention that each call produces a distinct URL (idempotentHint=false) or whether auth on the resulting URL is embedded or required.

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 tight sentences with the output front-loaded and the usage rule second. Nothing is redundant or 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 simple read-only presign tool with no output schema, the description conveys the return artifact and the primary use case. It leaves out whether the response also carries the expiry metadata, but the schema's expiresInMinutes note partly covers that.

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 every parameter — including the expiry clamping behavior — is documented in the schema itself. The description adds no parameter-level meaning 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?

The description states a concrete deliverable — a pre-signed URL for downloading an object — and implicitly separates itself from read_object with 'instead of reading them.' It is specific enough to distinguish the tool, though it does not name the sibling it replaces outright.

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 for binary or large objects instead of reading them' gives a clear selection condition and an implied alternative (reading the object via the read path). It stops short of stating when this is inappropriate, such as when the object is small or when the bytes are needed in-process.

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 flag destructiveHint=true and idempotentHint=false; the description goes well beyond by disclosing the exact timing semantics — the existence check happens once at mint time and the URL can still overwrite a key created afterward. That TOCTOU nuance is exactly the behavior an agent cannot infer from structured fields and materially affects correct use.

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 tight sentences plus a clarifying clause; the core artifact is front-loaded and every sentence carries non-redundant information about overwrite timing. 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-output-schema tool, the description covers the essential semantics, but it never states what the call actually returns (the signed URL and its effective expiry). The schema's expiresInMinutes text hints at this, yet with no output schema the return shape remains implicit.

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 baseline is 3, but the description adds real meaning to `overwrite` by explaining that the check is evaluated once at mint time rather than at upload time. The `expiresInMinutes` clamping/reporting behavior is left entirely to the schema, so it does not fully rise to 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?

States a specific verb and resource — minting a short-lived pre-signed PUT URL for direct upload — which is immediately distinguishable from create_download_link and the multipart/upload siblings. The 'PUT URL' detail and 'uploading content directly' phrase tell an agent exactly what artifact it gets.

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 supplies a precondition for the overwrite path ('refuses to mint the link if the key already exists unless overwrite is true'), which is useful usage context. However, it never says when to prefer this over write_object, start_multipart_upload, or presign_upload_parts, so the routing decision is left 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. 'Permanently' and 'Irreversible' reinforce destructiveHint but add little that the annotation does not already state, and the description omits what happens when the key does not exist or that the call is idempotent.

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 action and immediately followed by the risk warning. Nothing is wasted and there is no 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?

For a simple three-parameter delete with full annotations and no output schema, the description is serviceable but thin: it does not state the effect of deleting a missing key, confirmation requirements, or any permission needs. Adequate, not complete.

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 connectionId, bucket and key are each documented in the schema itself. The description adds no syntax, format, or constraint detail beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('deletes one object') and the qualifier 'one' implicitly separates it from the batch sibling delete_objects and the range sibling delete_prefix. It does not name those alternatives explicitly, so it is clear but not fully differentiated from 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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The agent must infer from 'one object' that bulk deletion should use delete_objects instead, which is a real but unstated distinction.

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 destructive/irreversible/idempotent, so restating 'Irreversible' is partly redundant; however the description adds real behavioral detail the annotations do not: partial-failure semantics ('Keys the provider refuses are reported and still exist — the rest are deleted regardless') and a batch ceiling of 1000 keys per call. It skips auth/permission prerequisites, keeping it short of 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?

Four short sentences, front-loaded with the effect and the irreversibility warning, then routing, then failure behavior and limits. No filler and every sentence carries distinct 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?

With no output schema, the description still covers the important return-behavior question (refused keys are reported and remain, others are deleted) plus the call-size limit, which is what an agent needs to invoke and interpret this destructive batch 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 the baseline is 3; the description still adds a constraint not present in the schema — a hard limit of at most 1000 keys per call — and clarifies that keys are full object keys. That extra constraint raises it above 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 ('Permanently deletes a list of objects') and immediately distinguishes itself from the sibling delete_prefix ('delete_prefix is for a whole folder') and implicitly from singular delete_object. An agent can route correctly 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?

Explicitly gives the selection condition ('Use this when you already have the exact keys') and names the alternative for the other case (delete_prefix for a whole folder). This is genuine when-to-use/when-not guidance, not implied.

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 and readOnlyHint=false, so the safety profile is covered. The description adds value beyond that by amplifying the blast radius ('EVERY object') and disclosing the dangerous bare-prefix matching behavior that could delete unrelated sibling keys — real behavioral context, not just a restatement.

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, zero waste, front-loaded with the destructive scope, then the prefix gotcha, then the safety workflow. Every sentence 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?

Annotations carry the safety/idempotency profile and there is no output schema to explain, so the description only needs to add operational context — which it does via scope, prefix risk, and the pre-check step. It could say more about partial-failure behavior, but it is complete enough for correct invocation.

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. The description goes further by explaining WHY keyPrefix must end in '/' — a bare prefix like 'old-logs' would also match 'old-logs-archive/...' — adding rationale and risk semantics the schema's terse description does not convey.

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 with clear scope: 'Permanently deletes EVERY object under a prefix.' This implicitly distinguishes it from delete_object (single) and delete_objects (list), though it does not name those siblings explicitly, so it lands just short of a 5.

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?

Provides a concrete prerequisite workflow: 'Call list_objects first and show the user what will be deleted before calling this.' Clear when-to-use context, but it never names an alternative tool (e.g., delete_object for a single key) or a when-not condition, so no explicit exclusion 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?

Annotations already establish the safe read-only, non-destructive, non-open-world profile. The description goes further by disclosing scan behaviour ('how many keys it examined and whether it stopped early') and the matching rules (case-sensitive, full key including prefix), which matter for predicting results. It does not cover rate limits or the failure mode when both glob and regex are omitted.

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?

Purpose and the mutual-exclusion rule are front-loaded, and each subsequent sentence carries concrete, non-redundant matching detail. Six sentences is on the long side, though the density is justified by the glob-versus-regex subtlety.

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 stating what the response reports (keys examined, early stop). With all six parameters schema-documented and the matching semantics fully spelled out, 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 baseline would be 3, but the description adds substantial meaning: glob must match the WHOLE key ('invoice' matches nothing while '*invoice*' works), '*' crosses '/' boundaries, '?' matches one character, and regex is searched anywhere in the key. This is exactly the semantics an agent needs and the schema terse descriptions do not supply.

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 (finds) and resource (objects) and immediately scopes it: 'at any depth under a prefix whose key matches a pattern'. It explicitly contrasts with the sibling behaviour of 'listing folders one level at a time', so an agent can distinguish it from list_objects without opening either 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 a hard usage rule ('Pass exactly one of glob or regex') and explains the trade-off between the two modes, which is effectively guidance on which parameter to pick. It does not name list_objects as the alternative to avoid, so the routing is 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral note — no object content is transferred — but says nothing about permissions, consistency, or behavior for missing keys, so with annotations doing the heavy lifting this is only modest added value.

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 with zero filler; the returned fields and the key constraint ('without reading it') are both delivered immediately.

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 no output schema, the description does enumerate the fields returned (size, content type, user metadata), which is what an agent needs to judge usefulness, and annotations cover the safety profile. Minor gaps remain around error cases and whether user metadata may be null when 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% with all three required params (key, bucket, connectionId) documented, including the pointer to list_connections for connectionId. The description adds no parameter-level meaning 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 the exact resource returned (size, content type, user metadata for one object) and scopes it to a single object. It implicitly separates itself from read_object by saying 'without reading it', but does not name the sibling explicitly, so it falls just short of a 5.

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 phrase 'without reading it' communicates the condition that selects this tool over read_object — use it when only metadata is needed and the bytes/egress should be avoided. It gives clear context but never names alternatives or exclusions outright.

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 the safety profile is covered. The description adds the useful scoping fact that results are limited to one connection, but says nothing about pagination, ordering, or result size for what is presumably a variable-length listing.

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 with no filler or redundancy. It is efficient, though its brevity is partly achieved by omitting rather than compressing 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?

For a simple one-parameter, read-only listing tool with full schema coverage and complete annotations, little is missing. Without an output schema, a note on return shape or pagination would help, but the essentials are present.

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 sole parameter is documented in the schema, including the cross-reference to list_connections. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lists the buckets') and scopes it to one connection, which is enough to separate it from list_connections and list_objects. It stops short of naming a sibling explicitly, so it lands at 4 rather than 5.

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 when-to-use guidance, no prerequisites, and no alternative named. The single sentence describes what the tool does, not when an agent should reach for it over list_connections or list_objects.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the token-scoped visibility model (own + shared) and the fact that entries carry a bucketPath limitation.

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, both earning their place, with the essential scope fact and the 'start here' dependency guidance front-loaded. No filler or restatement of the title.

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 no output schema, the description usefully pre-announces the key return field (bucketPath) alongside connectionId, giving the agent enough to chain calls. It omits other likely entry fields, but for a zero-param list tool this is close to complete.

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, so there is no parameter semantics to document and the baseline is 4. The description correctly spends no effort on inputs.

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 (lists storage connections) and sharpens the scope to what's available to this token — the user's own plus shared. This distinguishes it from sibling list tools like list_buckets and list_objects 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 strong usage direction: 'Start here: every other tool needs a connectionId from this list,' which makes the tool's role as a prerequisite explicit. It stops short of naming a when-not condition or an alternative, but the routing guidance is unusually clear.

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 past the annotations (which only declare readOnly/non-destructive/closed-world) by disclosing that parts are stored and billed until removed, that results are ordered by key rather than date, and that olderThanDays filters only the page the provider returned so a truncated answer can hide older uploads.

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-loads what the tool returns and why it matters, then layers the ordering and filtering caveats. Dense and semicolon-heavy, but each clause carries information; 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?

With no output schema, the description still conveys ordering, the truncation signal, and the filtering pitfall, which is what an agent needs to interpret results. It stops short of describing the returned record shape apart from the uploadId.

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 already 100%, but the description adds genuine semantics beyond it: prefix is framed as the tool for escaping a truncated page, and olderThanDays is flagged as a post-hoc filter over the returned page, which the schema does not say.

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 the exact resource and scope: multipart uploads that were started and never finished, with their parts retained. It implicitly separates itself from list_objects (completed objects) and points at abort_multipart_upload by noting the uploadId is the only way to abort one.

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 conditions for use ('where to look if an upload was interrupted or its id was lost') and guidance for narrowing with prefix when a page is truncated. It never names an alternative tool (e.g. abort_unfinished_uploads) as a when-to-use swap, so it stops short of the top band.

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 contributes real behavioral context beyond that: the page-at-a-time contract and the instruction to feed nextPageToken back as pageToken. It stops short of describing what a page entry contains, which it could since there is no output schema.

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, zero filler, with the core behavior front-loaded and the pagination and sibling-routing details following in priority order. 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?

With no output schema, the description usefully explains that results come one page at a time and names the nextPageToken continuation field. It does not describe the shape of returned entries or error conditions, leaving a modest gap for a listing tool, though nothing critical to correct invocation 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 baseline is 3, but the description adds cross-parameter workflow meaning the schema cannot state on its own: the nextPageToken-to-pageToken round trip and the default one-level vs recursive listing mode. This materially improves correct invocation of pageToken and recursive.

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 ('Lists objects and sub-folders under a prefix') plus the pagination constraint, so the agent knows exactly what it does. It also names the sibling tools it is not (find_objects, stat_prefix), making differentiation immediate.

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?

Explicitly routes alternatives: search by name or total a prefix goes to find_objects or stat_prefix 'rather than paging through it here.' It also states the default depth behavior and how to change it, so the when-to-use and when-not-to-use conditions are both covered.

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, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral context: the count is bounded by the connection's grant, it excludes old versions, delete markers, and multipart parts, and that a true restart means the position was refused. It doesn't describe rate limits or error handling, but the key operational traits are covered.

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 description is three sentences, front-loaded with the core action and then details. It is fairly compact but the third sentence about what is counted could be slightly more concise; overall it earns its place without excess.

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 the tool's complexity (bounded counting with continuation) and the absence of an output schema, the description covers how to handle the return value (continuation token), what happens on restart, and what objects are included. It is complete enough for an agent to use 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 the schema already defines each parameter. The description adds meaning about continuationToken: it's the 'position to continue from' and that a true restart signals the token was refused, which goes beyond the schema's basic description. This extra nuance earns a score above the baseline 3.

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 clear verb and resource: it counts a piece of a bucket and returns a continuation position. It distinguishes itself from siblings like stat_prefix or list_objects by focusing on counting with continuation, but it doesn't explicitly name an alternative for related tasks.

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 explicit step-by-step guidance on when and how to use the tool, including how to continue until the end and how to interpret a 'true restart'. It also clarifies that it counts current objects only, implicitly contrasting with tools that handle old versions or multipart uploads.

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/readOnlyHint/idempotentHint, but the description adds material behavior: the copy-then-delete implementation, the failure mode when the destination key exists, and the irreversibility of both overwrite and source deletion. That is real value 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?

Three compact sentences, each carrying a distinct fact (mechanism, precondition, failure/irreversibility), with the destructive semantics front-loaded. No filler or restatement of the name.

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 6-parameter mutation with no output schema, the description covers mechanism, preconditions, failure behavior and irreversibility. It stops short of noting cross-bucket/cross-connection scope or any permission requirements, which is the only 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%, so the baseline is 3, but the description adds meaning the schema lacks: overwrite gates a failure rather than merely 'replacing', and the overwrite/source-delete actions are irreversible. The destination-must-differ constraint also ties two otherwise-plain parameters together.

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 (moves) and resource (object), and goes further by explaining the mechanism: copy to destination then permanently delete source. That mechanism implicitly separates it from copy_object (non-destructive) and delete_object (single-resource removal) in the sibling list.

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 gives preconditions (destination must differ from source, fails on existing key unless overwrite) but never states when to choose this tool over copy_object plus delete_object. Usage is implied by the copied-then-deleted semantics rather than explicitly routed.

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 and idempotentHint=false, but the description goes well beyond them: it discloses irreversibility, the copy-before-delete ordering, and the concrete partial-failure outcome ('a run that stops part-way leaves the folder split across both places'). That failure-mode detail is exactly the kind of behavioral context an agent cannot get from annotations.

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, front-loaded with what happens and the irreversibility warning, then ordering semantics, then the prerequisite. No filler; the compound third sentence is dense but each clause carries distinct operational 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?

No output schema exists, yet the description covers prerequisites, failure modes, and formatting constraints, so an agent has enough to call it correctly. Gaps remain around when 'overwrite' is appropriate and when to prefer copy_prefix instead, which matter for a destructive bulk operation.

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 all six parameters are already documented in the schema. The description repeats the trailing-slash rule for both prefixes but adds nothing about the optional 'overwrite' parameter, so it does not exceed the baseline for a fully-covered 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 concrete verb+resource ('Copies every object under a prefix to another prefix and then deletes each source'), which is precisely the copy-then-delete semantics that separates it from copy_prefix and delete_prefix. An agent can distinguish this from the single-object move_object and the non-destructive copy_prefix 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?

Gives an explicit prerequisite workflow ('Call stat_prefix first and show the user what will move') and flags irreversibility, which implies caution. It never names copy_prefix or delete_prefix as alternatives, so the when-not-to-move choice is left 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 idempotentHint=true and destructiveHint=true; the description reinforces idempotency ('ask again... costs nothing, parts already uploaded stay uploaded') and adds the short-lived URL constraint. It never explains what makes the operation destructive (e.g., that presigned PUTs can overwrite an existing part), which is exactly the 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 tight sentences, front-loaded with what the tool returns, then the workflow obligation, then the recovery path. No filler and nothing repeated from the schema.

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 six-parameter tool with no output schema, the description covers the obligation loop (upload, keep ETags, re-request) that an agent needs to use it correctly. It does not describe the shape of the returned URL list, though the ETag/response contract is implied well enough for this workflow.

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 all six parameters, including the expiresInMinutes clamping behavior, are documented in the schema itself. The description only alludes to part numbers and adds no format or constraint detail 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 ('pre-signed PUT URLs') with the exact scope ('for the part numbers given'), which cleanly separates it from start_multipart_upload and complete_multipart_upload in the sibling list. An agent can identify the tool 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?

Lays out the whole multipart workflow: upload each part yourself, retain the ETag, every ETag is required at completion, and re-request any expired URL. It also says re-requesting is free and non-destructive, so the agent knows the fallback path when a URL expires.

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 read-only, non-destructive safety profile, so the bar is lower. The description still adds genuine behavior: large or binary content is returned as a download URL rather than bytes, and maxBytes only lowers (never raises) the server ceiling. It omits error/permission behavior, but the added context is valuable.

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 three tight sentences covering fallback behavior and sampling modes with no filler. Minor imprecision ('the answer' for the response) but every sentence 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?

No output schema exists, yet the description explains the two possible return shapes (inline content vs download URL) and the sampling parameters, which is the critical return-value context for a read tool. Remaining gap is the absence of any sibling routing guidance.

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 earns extra credit by framing head/tail as whole-line sampling from either end versus offset/length as a byte window, and clarifying maxBytes as a downward-only cap. This clarifies the interaction between parameters beyond the per-field schema text.

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: 'Reads a text object's content,' and it discloses the key behavioral distinction that large/binary objects return a download URL. It stops short of explicitly naming a sibling (e.g. get_object_metadata or create_download_link) to route the agent, so it is clear but not fully differentiated.

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 useful in-tool guidance on how to sample a large text file (head/tail vs offset/length), which is real usage context. However it never states when to choose read_object over siblings like get_object_metadata, create_download_link, or find_objects, so the when-to-use choice is left implicit.

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=true, idempotentHint=false), the description discloses that the rewrite is in place, that last-modified time changes, that content is untouched, and that names are normalized to lower case. That is meaningful behavioral context the structured fields do not carry; only authorization requirements and error semantics are absent.

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 tight sentences, front-loaded with the core mutation contract, then operand usage, then normalization, then side effects. No sentence is redundant and nothing important is buried at the end.

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 no output schema, the description covers the write contract, affected scope, and side effects well. It omits edge behavior (removing a name that does not exist) and any permission requirements, but those are minor relative to what is provided.

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 semantics not in the schema: the set/remove maps and their combined behavior, the merge-not-overwrite contract, and the lower-casing rule that applies to both written and removed 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?

The description states a precise verb+resource ('adds or replaces entries in an object's user metadata') and immediately defines the scope ('leaves every entry it does not name alone'), which separates it from the read-side sibling get_object_metadata and from whole-object writes like write_object.

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 explicitly instructs how to use the tool ('Pass set for entries to write, remove for names to drop, or both'), giving clear operative context. It stops short of naming when not to use this tool versus alternatives such as write_object or an overwrite-style call, so no exclusions are present.

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 and idempotentHint=false, but the description adds material facts annotations cannot: no object appears at the key until completion, parts are billed until then, and an upload must be explicitly aborted to stop the charges. That is exactly the lifecycle risk an agent needs before invoking.

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 the trigger condition, and every sentence carries information. The final workflow sentence is a compressed, dash-heavy telegraph ('Then: presign_upload_parts for URLs, PUT each part yourself keeping the ETag each returns...') that costs a little readability for its density.

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?

No output schema exists, yet the description names the return value (uploadId) and closes the loop on the full workflow and cleanup path. For a 6-parameter mutation with nested metadata, nothing an agent needs to call it 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 description coverage is 100%, so key, bucket, overwrite, contentType, userMetadata and connectionId are already documented (including overwrite's dual check at start and completion). The description adds no parameter-level meaning 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 ('Opens a multipart upload') and immediately demarcates the case it exists for: a file too big for a single PUT, with the 5 GiB S3 limit as concrete grounding. An agent can distinguish this from write_object without reading either 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?

Explicitly gives the when ('file too big for one PUT'), names the sibling tools to use afterwards (presign_upload_parts, complete_multipart_upload) and the escape hatch (abort_multipart_upload if you give up). No inference required to pick or sequence the tool.

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 the safety profile is covered. The description still adds real behavioral context beyond the annotations: recursive depth semantics and the critical trailing-slash pitfall where an unslashed prefix over-matches and yields a count delete_prefix would not act on.

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 filler. The measure outputs are front-loaded and the delete_prefix/slash caveat follows, so the most decision-relevant content lands first.

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 measurement tool with no output schema, the description names what is returned (count, bytes, newest, largest) and warns about the one prefix pitfall that would produce a misleading answer. Nothing needed to call it 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 baseline is 3, and the schema already documents 'prefix' (including empty = whole bucket). The description goes beyond it by explaining the trailing-slash matching semantics for the prefix parameter, adding genuine meaning the schema does not convey.

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 gives a specific verb (measure/count) and resource (objects under a prefix) and enumerates the exact outputs: object count, total bytes, newest and largest. It distinguishes itself from siblings like measure_bucket and list_objects by stating 'at any depth' under a prefix.

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 names a concrete trigger ('Call it before delete_prefix to tell the user what would be destroyed') and names the alternative tool to pair it with. It also gives an explicit when-to-do-something-different rule for the trailing slash, which is precisely the kind of routing guidance an agent needs.

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 and idempotentHint=false, and the description goes beyond them by stating the exact failure mode (key collision unless overwrite) and that overwriting is irreversible. It omits permission/auth requirements and anything about partial failure, but the added behavioral context is genuinely useful.

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 with zero filler, front-loading the core action and ending on the routing alternative. Every clause carries information the 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?

Covers encoding, overwrite failure semantics, irreversibility, and the alternative path, which is sufficient for a write tool whose annotations carry the safety profile. Minor gaps remain around whether content is size-limited or what a successful write returns, but no output schema exists so return detail is not strictly required.

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 baseline is 3, but the description adds semantic weight the schema lacks: it explains the interaction between key collision and the overwrite flag and warns that the overwrite path is irreversible. The contentType and connectionId parameters are left entirely to 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 ('Writes UTF-8 text to an object') and immediately scopes the content type to text, distinguishing it from binary-oriented siblings. An agent can tell this apart from create_upload_link or copy_object 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?

Explicitly routes binary or large content to create_upload_link, which is a clear when-not condition naming the alternative. It does not address other plausible siblings (e.g., set_object_metadata, copy_object), so guidance is strong but not exhaustive.

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