Tokenrip

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description still adds real behavior: a page may be short of limit when events are large, the cursor loop terminates on null nextCursor, and a purged artifact subject returns id null while its title is retained. It stops short of describing retention windows or authorization scope in detail.

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

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

Three sentences, front-loaded with the core read statement and then pagination before subject nuance. The middle sentence is dense but every clause carries operational information; the parenthetical about purged artifacts borders on over-detail but is genuinely non-obvious.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description doesn't need to explain return shapes, and it covers the two things an agent would otherwise get wrong: short pages and the cursor loop, plus the subject edge case. It omits filter-combination semantics and any note on authorization/visibility limits of team feeds.

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 each of the 7 parameters is already documented, which sets the baseline at 3. The description only adds marginal meaning beyond the schema for subject (the purged-artifact id-null case); team/type/actor/since/limit are simply restated or left 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?

The description opens with a concrete verb+resource ('Read authorized personal or team activity') and names the pagination and attribution model, so the tool's identity is unambiguous. It does not explicitly distinguish itself from adjacent read tools in the sibling list (connection_audit_recent, workspace_changes, notification_mailbox), which keeps it 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?

It gives actionable in-tool guidance for paging ('while nextCursor is not null, call again with cursor: nextCursor') and explains how to narrow with subject. However, it never states when to prefer this over auditing/changes/notification siblings, so alternative selection 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?

Goes well past the annotations: delete is soft (30 days in trash, returns dates), workspace items require a why, per-item revision entries cause CONFLICT refusal on changed items, and the tool returns all 'safe' failure IDs and counts without retrying destructive failures. That partial-failure model is exactly the behavioral context an agent needs before firing a destructive batch and is nowhere in the structured fields.

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 verb and scope, then the per-action constraints, then failure semantics — no filler sentences. It is telegraphic to the point of being slightly cryptic ('safe failure ID and count' is never unpacked), which costs a point.

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?

Destructive profile, per-action requirements, conflict behavior and partial-failure reporting are all covered, and an output schema exists so return shape needn't be restated. Minor gaps remain, such as whether a batch may span multiple workspaces/teams, which matters for a 200-item 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 83%, so the schema already documents most params; the description still adds value by spelling out the folder resolution precedence (artifacts' workspace, else team, else personal), the meaning of folder: null, and that move's folder/team are ignored on delete. The dependency between action and which params are legal is genuinely extra information.

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 pair and resource with scope: 'Apply move or delete independently to at most 200 artifacts.' The batch limit plus the fact that it takes artifactIds makes it unambiguous that this is the bulk counterpart to artifact_move/artifact_delete, and the first sentence alone is enough to choose it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the decision between the two actions: move requires a folder (or null to unfile), delete takes no folder or team and parks each item in trash for 30 days. It doesn't explicitly name artifact_move/artifact_delete as the single-item alternatives, so the batch-vs-single routing is implied by 'in bulk' 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?

Goes well past the annotations (destructiveHint=true, idempotentHint=true): it discloses that deletion is soft with a 30-day window, that the alias remains held, that repeats return the same dates, and that a stale expectedWorkspaceRevision yields CONFLICT. That is exactly the operational context an agent needs before a destructive write.

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 30-day trash semantics, then permissions, then the revision guard — no filler sentences. The telegraphic phrasing ('reads then answer DELETED with the dates') is slightly awkward, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, permission-gated mutation it covers the lifecycle (trash, 30 days, alias held), authorization per artifact type, the conditional 'why' requirement, conflict behavior, and idempotent replay. With an output schema present, no further return-value detail is needed.

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 nevertheless adds meaning by tying 'why' to the workspace-artifact case and by framing expectedWorkspaceRevision as an optional guard that refuses with CONFLICT on change. It adds conditional logic rather than just restating field strings.

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 and an unusual mechanism: it moves an artifact to the trash for 30 days rather than hard-deleting, and the alias stays held. That distinguishes it clearly from artifact_version_delete and trash_purge without naming them, though it never explicitly names a sibling alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete preconditions — standalone artifacts require owner or platform admin, workspace artifacts require internal admin or editor plus a 'why' sentence — plus the optional optimistic-concurrency guard. Clear context for when the call will succeed, but no explicit 'use trash_restore instead if...' routing.

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

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

Annotations only declare the generic profile (not read-only, open world, not idempotent, not destructive). The description adds real behavior: the copy is a new resource placed in the source workspace versus the caller's account depending on write access, and that a 'why' is mandatory for workspace writes but not for copies landing in your own account. It does not spell out error behavior for unreadable sources or that repeated calls create separate copies.

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 key verb is front-loaded and there is no filler, but the first sentence is a dense run-on that packs id source, endpoint, and three destination cases into one stretch, with nested parentheses ('(with why)', '(no why)'). It is compact rather than readable; the destination rules could be one short list instead of embedded clauses.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described, and the annotations cover the safety profile. Given a fork tool whose real complexity is destination and permission branching, the description covers the placement cases and the 'why' requirement; only edge cases (unreadable source errors, table rejection behavior) are left 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 artifactId, versionId, folder, team, title and why are all documented in the schema, which sets the baseline at 3. The description mostly echoes the folder id-or-slug resolution and the artifactId = current version semantics already in the schema, adding only the conditional framing of when 'why' is needed.

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: forks a readable non-table artifact into a copy, mapping to POST /v0/forks, and explicitly excludes table artifacts and names the two id sources (artifactId vs versionId). It is distinguishable from siblings like artifact_move, artifact_upload and artifact_get, though the purpose sentence is overloaded with placement conditionals that belong to usage guidance.

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 conditional branches for the copy's destination: source workspace when writable (with why), own account standalone for public-link-only reads, standalone for standalone sources, plus folder slug resolution order (copy workspace, else team, else personal). It never states when to fork rather than upload or read-then-create, so it is strong context but not full alternative routing.

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

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

Annotations already declare this as a safe, idempotent, read-only operation, so the description carries a lower burden. It adds that only 'authorized' artifacts are returned, which is useful access-control context, but it does not describe not-found/unauthorized behavior or any other operational details.

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. It communicates the operation, the resource scope, and the accepted identifier forms efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema, full parameter documentation, and rich annotations, the description is nearly complete for a simple one-parameter read tool. The only notable gap is that it does not explicitly route the agent away from similarly named sibling tools.

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

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

Schema description coverage is 100%, and the schema already documents the artifactId formats (bare alias, ~agent/alias, _team/alias, page URL) in detail. The description repeats the same identifier forms without adding new syntax or constraints, so baseline 3 is 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?

The description states a specific verb and resource ('Read authorized artifact metadata') and the accepted identifier forms. The word 'metadata' implicitly distinguishes it from content-reading siblings such as artifact_get_content, but it does not explicitly name or contrast those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is for retrieving metadata rather than content, but there is no explicit guidance on when to choose it over artifact_get_content, artifact_read, or artifact_list. No when-not conditions or alternatives are named.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is low. The description still adds value by noting the content can be served through an 'authenticated immutable version resource' and that full content is returned inline, which tells the agent about auth requirements and version immutability.

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 with the main capability front-loaded and the sibling exclusion trailing. 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?

With an output schema present and full parameter documentation, the description covers what is needed to invoke the tool correctly. The only meaningful gap is not distinguishing itself from adjacent artifact readers.

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%, including the versionId default and artifactId alias/URL formats, so the schema does the heavy lifting. The description only reinforces 'complete' content and the version-resource concept, 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 and resource ('Read complete file content') and clarifies the two access modes (inline vs authenticated version resource). It partially disambiguates from siblings by ruling out tables, but leaves the distinction from artifact_read/artifact_get unexplained.

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 one explicit routing rule ('Use table_get_rows for tables') and implicitly covers version selection via the versionId default. However, it offers no guidance against the much closer siblings artifact_read and artifact_get, so an agent still has to guess which artifact-reader to pick.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so safety is covered. The description adds real value by guaranteeing stable ordering (updatedAt desc, then ID desc) and complete offset continuation, but says nothing about result-set size, total counts, or behavior when filters conflict.

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 waste. The pagination rule and the sort guarantee are both front-loaded and immediately actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and full parameter coverage, the description only needs to explain continuation and ordering, which it does. Minor gap: it never clarifies the default scope (personal vs team vs workspace) when no filter is supplied.

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 eight parameters are already documented, including offset as "the previous page's nextCursor". The description merely restates the offset/nextCursor relationship rather than adding format or precedence rules 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 with scope: "List owned or team artifacts". An agent can distinguish it from artifact_get or search, though it does not name the sibling alternatives (search, folder_list, trash_list) that also surface artifacts.

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 implied by the pagination instruction ("Follow nextCursor as offset"), but there is no explicit when-to-use versus search or folder_list, and no note on when the team/workspaceId filters are mutually exclusive beyond what the schema already says.

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. The description adds genuinely useful behavior beyond them: the CONFLICT refusal semantics of expectedWorkspaceRevision and the mandatory 'why' for workspace items. It doesn't explain what the destructive aspect means concretely (moving out of a source folder) but the annotations plus these details make the contract clear.

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?

Compact and front-loaded: the move/unfile duality leads, then the folder resolution rules, then the revision guard. Dense but every clause carries a distinct rule; the parenthetical resolution order is slightly redundant with the schema but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers the mutation contract (folder required, null unfiles, why required for workspace, revision conflict). Only gaps are cross-workspace/team permission behavior and where the artifact ends up on failure — minor for a move 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 description coverage is 100%, so every parameter (folder, artifactId, why, team, expectedWorkspaceRevision) is already documented in the schema. The description largely restates the schema's folder resolution order and the 'why' requirement rather than adding new 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 ('Move an artifact into a folder') plus the inverse operation ('or unfile it'), which immediately separates it from sibling tools like artifact_update, artifact_delete, and folder_* tools. An agent can identify the operation 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?

Gives clear operational context: when folder is null the artifact is unfiled, workspace artifacts require 'why', and expectedWorkspaceRevision triggers a CONFLICT refusal. It does not name a sibling alternative (e.g., artifact_update for renaming) or state permission prerequisites, so it falls short of explicit when/when-not routing.

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

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

Despite annotations already flagging destructive and idempotent, the description adds real operational detail: metadata 'replaces the stored object', table re-keys yield STATE_CONFLICT/INVALID_INPUT and 'changing nothing', and sharing 'exposes full artifact history'. Conflict semantics (CONFLICT on stale revision) and the bounded receipt are also disclosed.

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

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

Front-loaded with purpose, and every clause carries a rule or error code with no filler. The cost is that roughly fifteen distinct conditional rules are crammed into one unbroken paragraph, making some constraints easy to skim past.

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 an 11-parameter mutation tool with an output schema, this covers the missing pieces an agent needs: required combinations, revision-conflict behavior, visibility/audience coupling, metadata replacement semantics, and schema-validation failure modes. Return values are correctly left to the output schema.

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

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

Schema coverage is 82%, so the baseline is 3, but the description contributes cross-parameter rules the schema cannot express per-field: which field combinations make expectedWorkspaceRevision required vs optional, and how visibility interacts with audience ('audience internal turns link off'). Folder/alias null behavior is repeated from the schema rather than extended.

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?

Opens with a specific verb and resource — 'Patch artifact details, visibility, folder or workspace audience without creating a version' — and adds the distinguishing trait that no version is created. It never names the close sibling artifact_update, so an agent must infer the delta between the two on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete preconditions: 'name at least one' field, workspace artifacts require a why except for visibility-only patches, and expectedWorkspaceRevision is mandatory with description/metadata but optional for title/alias/folder/audience/visibility. It lacks any explicit statement of when to prefer artifact_update or artifact_move instead.

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 (non-read-only, non-destructive, open-world), the description discloses real behavior: typed teams lists undergo authorization before standalone creation, every version is stored in full and counts against the owner's storage, and the receipt is bounded but grants complete immutable content access. These are cost and auth facts an agent cannot infer from readOnlyHint/destructiveHint.

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 is front-loaded and every clause carries a constraint rather than filler. The telegraphic compression ('homes it there', 'folder files it') makes it slower to parse than it needs to be for a 16-parameter tool, but nothing 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?

With 16 params, an output schema and annotations already supplied, the description covers the decisions an agent must make: workspace vs. standalone, folder resolution, handoff, storage cost, and the table escape hatch. Return values need not be explained because an output schema exists.

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

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

Schema coverage is 75% and the schema already documents most fields, so the baseline would be 3; the description adds cross-field constraints the schema does not express (a workspace item takes no visibility, teams or publicAsset; no expected revision is needed; folder resolution order workspaceId → team → personal). It doesn't clarify alias, parentArtifactId or creatorContext, so it stops short of full coverage.

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 opening sentence gives a precise verb and resource ('Publish text as a versioned artifact') and the body scopes it further into workspace vs. standalone modes. It also explicitly routes a neighboring use case away ('data that grows by adding records belongs in a table'), letting an agent distinguish this from table_append_rows 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?

It states the branch conditions clearly: workspace items need why and take no visibility/teams/publicAsset; standalone items can use those and are where typed teams lists are authorized. It names alternative paths explicitly (artifact_share_policy for later public readability, tables for growing data). What's missing is any guidance versus artifact_upload, artifact_patch or artifact_update.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations by stating the content is complete and immutable, and that table artifacts return a redirect rather than direct content. It still omits details like size limits or auth requirements, but the key behavioral quirks are disclosed.

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 with no wasted words. The core action is front-loaded, followed by the important table exception. 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?

With an output schema, full parameter coverage, and rich annotations, the description provides enough context to call the tool correctly. It explains the main return shape at a high level and the table redirection. It could be slightly more complete by clarifying its relationship to artifact_get and artifact_get_content, but the essential behavior is covered.

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 artifactId and versionId are fully documented in the schema. The description does not add any parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema carries parameter semantics.

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: read artifact metadata and complete immutable file content. It also clarifies a special case for tables, redirecting to table_get_rows. It is clear, though it does not explicitly distinguish itself from siblings like artifact_get and artifact_get_content.

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 only explicit usage routing is for tables: they return a typed direction to table_get_rows. There is no guidance on when to use artifact_read versus artifact_get, artifact_get_content, or artifact_list. The implied use case is reading full artifact data, but alternatives are not addressed.

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

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

Annotations already flag destructive=true and openWorldHint=true, so the bar is lower; the description still adds real context by explaining that 'link' makes the artifact readable by anyone with the URL and that 'public' additionally makes it 'listed'. That exposure/consequence detail is exactly what 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?

Two sentences, no padding, and the operation is front-loaded before the visibility options. The compressed, fragmentary style ('beyond its home', 'link: internal editors') costs some readability but wastes no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so explaining return values is optional (the URL mention is a bonus), and annotations cover the safety profile. However, for a destructive sharing change the description omits the conflict-guard parameter and gives no hint about reversibility or permission requirements.

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 only lightly supplements: it says 'link ... needs no why' (partially restating the schema's note) and 'returns the URL', but says nothing about expectedWorkspaceRevision or how CONFLICT is surfaced.

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 ('Set who beyond its home can read an artifact') and enumerates the three resulting states. An agent can tell this is a sharing/visibility mutation, though the boundary versus sibling artifact_publish is not drawn.

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 conditional guidance embedded in fragments ('standalone only: listed', 'A workspace artifact takes private or link'), which is useful but telegraphic. It never states when to prefer this over artifact_publish or artifact_update, and the 'internal editors' phrase is left unexplained.

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, it discloses atomicity, that every version is stored in full and consumes the owner's storage quota, that a stale expectedVersionId produces CONFLICT, and that empty text is valid. These are real behavioral consequences an agent cannot infer from readOnly=false / destructive=false alone.

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

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

Front-loaded with the core action, then constraints, then alternatives — no wasted sentences. The storage/quota and prune tail is slightly beyond what is needed to invoke the tool, but it earns its place by steering behavior away from version spam.

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 9-parameter mutation with an output schema and annotations already present, the description covers the operation model, conflict handling, storage cost, and sibling alternatives. Nothing an agent needs in order 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?

Adds meaning beyond the 78%-covered schema by tying expectedVersionId to the workspace requirement and pointing at currentVersionId as its source, and by framing content vs base64Content as mutually exclusive alternatives. The remaining parameters (why, description, creatorContext, filename, mimeType) get no treatment in the description, but the schema already documents most of them.

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 mechanism: atomically create a new version from either text (content) or a base64 file. It also distinguishes itself from siblings by naming artifact_patch for audience changes and artifact_versions_prune for cleanup, so an agent can route correctly without opening other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use and when-not-to-use guidance: use artifact_patch to change a workspace audience, use table_append_rows-style tables for record-growing data, and call prune only on the person's request. It also prescribes the conflict recovery loop — re-read, then retry with currentVersionId.

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 non-read-only, non-destructive, non-idempotent, open-world. The description adds substantive behavior: full version storage contributing to owner storage quota, no expected-revision requirement, and bounded content access on return. That is real context beyond the annotations, though the 'bounded content access' phrasing is vague.

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, but the middle sentences are dense run-ons with nested parentheticals ('folder files it: a folder id, or a slug (in workspaceId, else in team, else your personal folders)') that slow comprehension. Information density is high but readability suffers.

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 13-parameter tool with an output schema, the description covers the critical decision points (workspace vs standalone, folder resolution, storage implications). Unmentioned params like creatorContext, inputReferences, and parentArtifactId are documented in the schema, so the gap is minor.

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 69%, so the schema already documents most parameters including `why`, `folder`, `teams`, and `audience`. The description reinforces the `folder` slug-resolution order and the workspace-item constraint on `why`/`teams`, but mostly restates what the schema descriptions say. Average-value addition only.

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 ('Upload a strictly encoded base64 file') immediately, and clarifies the workspace-item versus standalone distinction. It does not name sibling tools directly, but the closing contrast with tables gives partial differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives conditional routing: workspace items need `why` and take no `teams`, standalone creation requires typed team authorization, and record-growing data belongs in a table instead. The alternatives are implied rather than named (no mention of artifact_bulk or bundle tools), but the when-to-use conditions are 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?

Goes well beyond the annotations (destructive/idempotent/not read-only) by disclosing the last-version guard, the per-scope authorization model, the CONFLICT semantics for a stale expectedWorkspaceRevision, and NOT_FOUND for unreadable versions. These are the exact behavioral traits an agent needs before attempting a destructive call.

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?

Dense and front-loaded: the core rule (delete one version, except the last) comes first, followed by permissions and concurrency. The telegraphic fragments ('Standalone: the owner.') are efficient but slightly strain readability.

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 operation with an output schema and rich annotations, the description covers purpose, authorization, constraints, and failure modes. Nothing material is missing for an agent to decide and invoke 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 all three parameters are already documented, including `why` being required for workspace items and expectedWorkspaceRevision's CONFLICT behavior. The description restates these ('with why', 'expectedWorkspaceRevision is optional and refuses...') but adds no new syntax, format, or edge-case meaning.

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 ('Delete one version by its own id') and clarifies that versionId identifies the artifact, which distinguishes it from artifact_delete (whole artifact) and artifact_versions_prune. It does not name those siblings explicitly, so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when/who guidance: standalone artifacts require the owner, workspace artifacts require internal admins or editors plus a `why`, and the last remaining version cannot be deleted. It lacks an explicit contrast with bulk alternatives like artifact_versions_prune, so the routing is clear but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavioral context beyond them: large diffs are served via a hash-guarded resource, and deleting the base version invalidates continuations. Those are non-obvious operational constraints 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?

Front-loaded and short, with every clause carrying information. But it is a single dense sentence with stacked parentheticals and semicolons that is noticeably harder to parse than it needs to be; splitting the two modes into separate sentences would cost nothing and gain clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need no explanation, and the three optional parameters are fully documented in the schema. The description closes the remaining gaps that matter for correct invocation: mutual exclusivity of modes, range semantics, and large-diff/invalidation behavior.

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 each parameter, and description text largely restates it ('not later', 'of the same artifact'). The one added nuance is framing fromVersionId as a range selector ('everything the versions from fromVersionId on changed'), which clarifies intent but not syntax.

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 ('Read a complete text or CSV version diff') plus the API path GET /v0/diffs, so the agent knows exactly what it returns. It doesn't name a sibling to distinguish itself from artifact_versions or artifact_get_content, so the differentiation is left implicit.

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?

'versionId (by its own id), or artifactId alone (its current version)' versus 'with fromVersionId... everything the versions from fromVersionId on changed' clearly maps each parameter mode to a distinct question the caller might have. No explicit when-not or named alternative among the ~90 siblings, which keeps it out of 5 territory.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered newest-first and pagination is driven by a nextCursor fed back as offset, which the schema does not reveal (there is no cursor parameter defined).

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 with zero filler, and the ordering constraint is front-loaded before the pagination instruction. 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?

With an output schema present, return values need no explanation, and the description covers ordering and pagination strategy, which is the main non-obvious behavior. It falls just short of 5 because the limit parameter's tuning and the offset ceiling are left entirely to the schema.

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

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

Schema coverage is 33%: artifactId is documented, but limit and offset carry no schema descriptions beyond defaults and ranges. The description partially compensates by explaining how offset is derived from nextCursor, but it says nothing about limit (default 50, max 100) or the consequences of exhausting the offset cap.

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

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

The description names a specific verb and resource ('List artifact versions') and adds the sort order ('newest first'), which distinguishes it from artifact_get_content or artifact_version_diff. It doesn't explicitly differentiate from adjacent siblings like artifact_version_delete or artifact_versions_prune, but the read-only listing purpose 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?

Usage is implied by 'List artifact versions' plus the pagination note, so an agent can infer this is the call for retrieving version history. However, no alternative is named (e.g., when to use artifact_version_diff instead) and no prerequisites or exclusions are stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds genuinely new behavioral facts: deletion is permanent, nothing goes to the trash, and tables raise INVALID_TYPE. That goes well beyond the structured hints, though permission requirements or what the response reports on success are not 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?

Four compact sentences with the destructive warning front-loaded and the storage rationale close behind. The trailing INVALID_TYPE note is short and earns its place as an error-prevention hint, though the dense parenthetical about `keep` slightly interrupts the flow.

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, four-parameter tool with an output schema, the description covers the irreversible consequence, the retention rule, the storage motivation, and the main error mode. Return values are handled by the output schema, so nothing an agent needs to invoke this safely 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 all four parameters including `keep`, `why`, and `expectedWorkspaceRevision` are already documented in the schema. The description only restates the `keep` default behavior that the schema itself explains, adding no semantics beyond what structured fields provide. 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 delete an artifact's old versions') plus the exact scope (keeps current + newest `keep`). The table sentence hints at what it is not (a rows tool), but the closest sibling, artifact_version_delete, is never named, so the agent must infer that this is the bulk/multi-version variant rather than the single-version delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit gating condition ('prune only when your person asks') and a motivation ('frees storage; every version counts toward the owner's storage'). It stops short of naming alternatives, so an agent deciding between this and artifact_version_delete for a one-off removal gets no direct routing advice.

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 the write profile (readOnly=false, idempotent=false, destructive=false), yet the description adds real substance: the version is immutable and appended (prior versions survive), activation flips the live version, and the receipt is bounded. It also notes that 'why' is accepted but not recorded, which is genuinely non-obvious. Missing: permissions required and any archive size limits.

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, front-loaded with the action and target, with no filler. The field-partition clause is dense but each clause 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?

An output schema exists, so return values need no explanation, and the 'bounded receipt' pointer usefully signals truncation. For a mutating deploy tool with no annotation-level detail on auth or archive constraints, though, a sentence on required permissions or what happens to the previously live version would round it out.

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; the description earns an extra point by explaining the field partition — 'A version takes description, entrypoint and spa; title, slug and visibility belong to the bundle' — which tells the agent why certain fields are absent and prevents wasted attempts to set them.

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 and resource: appends an immutable ZIP version to a bundle and activates it, which clearly separates it from read-side siblings like bundle_get. It also delineates version-level fields from bundle-level fields. It does not, however, distinguish itself from bundle_rollback or deploy_bundle, which an agent could plausibly confuse with it.

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 only routing guidance is 'use bundle_get for complete metadata', which addresses the receipt rather than tool selection. There is no statement of when to prefer this over bundle_rollback (revert to a prior version) or deploy_bundle, nor any precondition such as requiring the bundle to already exist.

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?

While annotations already flag destructiveHint and idempotentHint, the description adds non-obvious consequences the annotations cannot convey: the live site stops serving, the slug remains held, retention is 30 days, and repeated calls return the same dates. That is exactly the extra context an agent needs before triggering a destructive action.

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 action and its consequences, then authorization and idempotency. Nothing is wasted and nothing important is buried.

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 output schema covers return values (the dates), and the description covers the destructive consequences, retention period, authorization, and idempotency. An agent has everything needed to decide and call 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 (bundleId accepted in id/slug/URL forms, and the unrecorded 'why') are fully documented in the schema. The description adds no parameter-level detail beyond the owner/admin authorization note, 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 and resource with its exact semantics: 'Move a bundle to the trash for 30 days.' The soft-delete framing plus 'slug stays held' distinguishes it from a hard delete and implicitly from trash_purge/trash_restore without needing to name them.

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 ('The owner or a platform admin') and the 30-day window that tells an agent this is recoverable, which is the key usage consideration. It stops short of explicitly naming the alternative tools (trash_restore for undo, trash_purge for permanent removal).

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=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: large payloads come back as complete base64 byte chunks resumed via sha256+offset, and metadata changes force a restart of the pagination—exactly the kind of operational constraint an agent cannot infer from structured fields.

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 with no filler and the core action front-loaded, but the chunking sentence is telegraphic and grammatically broken ('Large JSON is complete base64 byte chunks'), which forces re-reading and blunts the otherwise efficient structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return shape needn't be restated, and the description covers the two things that matter for correct invocation: accepted identifier forms and the continuation/restart protocol. It stops short of stating chunk size limits, what a partial response looks like, or error behavior, which would be needed for full completeness on a paginated read.

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 only 50% and the nested continuation object has no property descriptions at all, so the description must compensate—and it does, explaining that bundleId accepts an id, a personal slug, a live URL or a page URL, and that continuation is a cursor carrying a chunk hash plus an offset. Minor flaw: it says 'nextOffset' while the schema property is named 'offset', a naming mismatch that could confuse an implementer.

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?

Opens with a specific verb+resource: 'Read full bundle metadata and manifest', which clearly separates it from bundle_list (enumeration) and bundle_get_file (file payload). It does not explicitly name those siblings, but the 'full metadata and manifest' framing makes the scope distinguishable.

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 implied through the continuation instructions ('pass chunk.sha256 and nextOffset in continuation') and the restart caveat, which effectively tell the agent this is a potentially multi-call read. However there is no explicit when-to-use/when-not guidance and no routing to bundle_list or bundle_get_file for the alternative cases.

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

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

Annotations already declare readOnlyHint, non-destructive, idempotent, and closed-world behavior. The description adds valuable behavioral context beyond annotations: reading in base64 chunks, rechecking bundle readability, and verifying exact version membership on every read.

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 front-loaded and compact: it first states the action, then explains first-read and continuation behavior, then notes revalidation. It is appropriately sized for a chunked file-read tool with little wasted text.

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 tool has annotations, a full schema description coverage, and an output schema, so the description does not need to explain return values in detail. It supplies the key chunking and continuation semantics an agent needs to call the tool 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 documents each parameter. The description still adds useful linkage semantics: the first read resolves directories/SPA fallback, while continuation reads use the returned versionId, exact path, and nextOffset as offset.

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: read complete file bytes from a bundle as base64 chunks. It is clear what the tool does, though it does not explicitly distinguish itself from similar sibling tools such as artifact_get_content or bundle_get.

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 explains continuation usage by saying to use the returned versionId, exact path, and nextOffset for subsequent reads. However, it does not state when to use this tool instead of alternatives or what prerequisites apply to the first read.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so safety needs no restating. The description adds genuinely non-obvious behavior beyond them: default sort order ('newest activity first') and the cursor-invalidation rule ('changed collections require restart'). It omits any mention of page-size behavior or the response envelope, which keeps it off 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?

Three short sentences with zero filler, front-loading scope and ordering before the sibling pointer and the pagination caveat. Every clause carries information an agent would otherwise have to infer.

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 rich annotations and an output schema, the description needn't cover return shape, and it correctly covers ordering and cursor invalidation. But for a paginated list tool it leaves page-size semantics unaddressed and uses a cursor name that does not match the schema, so an agent still has gaps at call time.

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 0%, so the description must carry the load. It explains the cursor's continuity contract (pass it back; restart if the collection changed), but refers to it as 'nextCursor' while the schema property is 'cursor', a naming mismatch that could cause a wrong argument, and it never mentions 'limit' at all (default 50, max 100).

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 ('Page every owned bundle') plus a scope ('owned') and an ordering guarantee ('newest activity first'), and explicitly routes full-detail needs to bundle_get. An agent can distinguish it from bundle_get and bundle_get_file 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?

Names the alternative explicitly ('Full metadata and manifest: bundle_get'), giving a clear selection rule for the browse-vs-inspect decision. It stops short of stating when listing is inappropriate (e.g., when the bundle name/id is already known), so it is not a full when/when-not specification.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false; the description usefully corroborates idempotency ('an existing immutable version; no new version is created'). However, it never explains what destruction means here — whether the currently active version is replaced, whether deployments are affected, or that no history/undo exists (that fact lives only in the 'why' parameter 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?

A single tight sentence with zero filler, and the key fact (existing version, nothing new created) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained, but for a destructive, idempotent write with no audit trail, the description leaves out the operative consequence (active version is swapped, no workspace history, no way back). One sentence is not quite enough for an irreversible-by-design mutation.

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 version, bundleId, and why are fully documented in the schema, and 'immutable version' aligns with the version parameter. The description adds no meaning beyond the schema, 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 (activate) and resource (an existing immutable version), which effectively describes a rollback. It implicitly contrasts with creating a new version, though it never uses the word 'rollback' or the bundle resource from the tool name, so an agent must connect 'activate version' to 'bundle_rollback' itself.

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 clause 'no new version is created' hints that bundle_create_version is the alternative path when a new version is needed, but the description never names a sibling or states when to choose rollback versus deploy_bundle or create_version. Usage is only 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 mark this as destructive, non-idempotent, and not read-only. The description adds important behavioral detail: the cutoff is relative to execution time, so repeat invocations may delete newly aged rows, and the scope covers every caller's rows within the selected personal or team-owned connection.

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 two compact sentences with the destructive action front-loaded. The parenthetical qualifications are dense but all carry operationally relevant meaning, and there is no redundant restatement of schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema and rich annotations, the description supplies enough context for an agent to call this destructive tool correctly. It covers the deletion target, ownership scope, connection resolution, default age cutoff, and time-relative repeat behavior.

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

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

Schema coverage is 75%, so the schema already documents much of the parameter surface. The description adds useful semantics for the connection parameter, including id-only lookup, disabled connections, optional team scoping, and personal versus team ownership resolution.

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: deleting audit rows older than N days for one connection. It also defines the connection resolution scope and the ownership boundary, making it clearly distinct from a read-only sibling such as connection_audit_recent.

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 clear context for which connection forms are valid, including disabled connections and personal versus team-owned connections. It does not explicitly name the read-only alternative or state when not to use this tool, 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds the recency cap (not full history) and the delivery mechanism (inline or live-hash-guarded resource chunks), which is useful, but ordering and row contents are left implicit.

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 is front-loaded, but the phrasing is convoluted and run-on ('which you must be able to call', 'complete live-hash-guarded resource chunks'), making it denser than needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations are rich, so return values and safety are covered externally. The description adds the recency limitation and delivery mode, leaving only minor gaps like sort order of returned rows.

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 67% and the connection param already documents id/name/team/disabled semantics. The description largely restates those rules and repeats the limit default/max that the schema already declares, adding little new 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?

The description states the resource precisely (recent connection-call metadata, every caller's rows for one connection) and distinguishes the scope from a full historical audit. The verb is somewhat implicit (carried by the title 'Show') but an agent can still tell what it retrieves.

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 clear conditions for the identifier (id alone, including a disabled connection, or name with optional team) but only implies usage scope via 'recent... not a full historical audit.' It never names the alternative (e.g., connection_audit_purge or a full-audit sibling) or 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?

Adds substantial behavior beyond the read-only annotations: stored secrets are omitted, disabled connections are excluded by default, canCall explains whether each connection is callable, and large lists are returned in resource chunks. This gives the agent useful expectations for filtering, security, and response behavior.

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 front-loaded with the main action and scope, and most sentences carry useful information. The final phrase 'complete live-hash-guarded resource chunks' is somewhat opaque implementation jargon.

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 two-parameter read-only list tool with an output schema and full annotation coverage, the description supplies enough context about scope, secret omission, disabled filtering, callability, and chunking. No essential invocation detail appears to be 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 the schema already explains both 'team' and 'includeDisabled' including the false default. The description reinforces these semantics but does not add meaning beyond the structured parameter documentation.

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 complete public connection configuration' for an account or team. The scope is clear, but it does not explicitly differentiate itself from sibling audit tools such as connection_audit_recent.

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 account-versus-team context is clear from the 'team' parameter discussion, but there is no explicit when-to-use guidance or comparison to alternatives. Usage is implied 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?

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the bar is lower, and the description still adds real value: 'immutable' signals that existing versions are never mutated, and 'bounded receipt' warns that the response is truncated relative to the stored content. It does not mention auth/permission requirements or slug-uniqueness failure behavior, which remain in the schema only.

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, with the action and the immutability/return-size caveat front-loaded before the follow-up routing. Nothing repeats the tool name or 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 an output schema present, the description does not need to enumerate return fields, and its 'bounded receipt' note usefully frames why the output is partial. For an 8-parameter write tool with full schema coverage and clear annotations, this is close to complete; only sibling differentiation and any permission preconditions 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%, so every parameter including the enum on visibility and the odd 'why' field is documented in the schema itself. The description adds nothing about parameter formats or defaults beyond the schema; 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 ('Deploy a base64 ZIP as an immutable file-tree version'), which tells an agent exactly what is produced and that the result is content-addressed/immutable. It does not distinguish itself from close siblings such as bundle_create_version or artifact_upload, so the boundary between near-identical write tools is left implicit.

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?

'Returns a bounded receipt; bundle_get reads full metadata/manifest and bundle_get_file reads complete files' explicitly routes the agent to the right follow-up tool rather than leaving it to guess. There is no statement of when to prefer this over bundle_create_version, but the read-path guidance is concrete and actionable.

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 declare it is a non-read-only, non-destructive, non-idempotent create. The description adds genuinely new behavior: default audience resolution by creator type (internal vs external) and an explicit refusal case for external editors requesting internal. That is useful authorization context beyond the annotation set; it omits what happens on slug collision, which the non-idempotent hint implies errors.

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 dense sentences, front-loaded with the create variants before the constraint rules. Nothing is padding, though the compressed phrasing ('go alone') takes a second read.

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 five parameters, a full schema, annotations, and an output schema present, the description supplies the missing piece: combination rules and permission defaults. Conflict/duplicate handling on slug is the one gap, minor given the non-idempotent hint and output schema.

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

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

Schema coverage is already 100%, so baseline would be 3, but the description adds cross-parameter semantics the per-property schema cannot express — mutual exclusion of team/workspaceId and the audience-workspaceId dependency. Only 'why' and 'slug' constraints are left 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 (Create) plus the exact resource variants it produces — personal, team (team), workspace (workspaceId) — and names the parameter that selects each. An agent can distinguish it from folder_update/folder_delete without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete selection rules: 'team and workspaceId go alone', 'audience requires workspaceId', 'a workspace folder needs why'. That is clear guidance on which parameter combination to use, though it stops short of naming siblings or stating when to prefer folder_update over a create.

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 destructive/idempotent, and the description goes well beyond them: 30-day retention window, folders disappear from listings, file reads return DELETED, files retain their filing and return with the folder, and the slug stays reserved. The idempotency claim is even given an observable ('returns the same dates').

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 action, which is good, but the middle is compressed into colon-chained clauses ('its slug: in workspaceId when given, else in team, else one of your personal folders') that must be re-read. It also duplicates schema text rather than spending those words on new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations carry the safety profile, so the description's remaining job is effects and permissions — both covered (what leaves listings, what reads return, how recovery works, who may call it). Nothing an agent needs to invoke 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 all five parameters are already documented; the description largely restates the folder resolution rule that appears verbatim in the schema. It adds only a marginal hint about expectedWorkspaceRevision being optional, and the phrasing 'with why (expectedWorkspaceRevision optional)' is garbled enough to add little.

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 scope: 'Move a folder, and the files in it, to the trash for 30 days.' This is clearly distinguishable from folder_update (editing) and trash_purge (permanent removal) among the 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?

Gives concrete gating conditions: permissions vary by folder kind (personal: owner; team: any member; workspace: delete-content right plus why), and notes repetition is safe. It stops short of explicitly naming the recovery path (trash_restore) or stating when not to use it versus trash_purge, so it is clear context but not full alternative routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: the result is paginated, must be followed to completion, and is ordered by folder ID — useful detail an agent needs to loop correctly.

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 scope options are front-loaded and the pagination rule follows immediately after.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present and annotations carrying the safety profile, the description only needs the listing scope and pagination contract, both of which it supplies. Minor gaps remain around limit defaults and mutually exclusive scope parameters.

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 50% — team and workspaceId are documented in-schema, while limit and cursor are not. The description compensates partially by explaining how to follow pagination, but it refers to 'nextCursor' while the input parameter is 'cursor', which can cause an agent to look for the wrong field, and it never mentions the limit parameter or its bound.

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 (list) and resource (folders) and enumerates the three scoping modes (personal, team, workspace). It implicitly separates itself from folder_show, but never names siblings like folder_create or folder_show explicitly, so differentiation is left to the reader.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use each scope by tying 'team' and 'workspaceId' to their parameter names, which is helpful context. However, it gives no explicit guidance on what happens if multiple scope parameters are supplied, nor does it point to alternatives.

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: discloses atomicity, the bulk-limit refusal, and the CONFLICT-on-revision-mismatch behavior with expectedWorkspaceRevision. Combined with idempotentHint and destructiveHint, the agent knows this is a state-changing, re-runnable operation with defined 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?

Front-loaded with the action, and each clause (scope, params, why, bulk limit, revision guard) carries information. It is dense and semicolon-heavy but not padded; a slightly cleaner structure would push it higher.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema and full annotations present, the description covers mutation semantics, preconditions, and one failure mode. The main residual gap is what 'shared' actually means (visibility scope), but the essentials for correct invocation 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: folder is id or slug-with-workspaceId, the workspace is the folder's own, why is required, and expectedWorkspaceRevision is an optional conflict guard. This exceeds what the schema fields state individually.

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 (make shared) and resource (a workspace folder plus all its current child artifacts), plus the atomic scope. This is clearly distinguishable from siblings like artifact_share_policy or folder_update, which act on individual artifacts or folder metadata.

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?

Conveys the operational context well: 'all of its current child artifacts' implies only existing children are covered, and 'Refuses selections above the workspace bulk limit' flags a use precondition. It does not explicitly route to an alternative tool, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety behavior needs no restating. The description adds one genuine piece of behavioral context — that artifact_count is a live count and is null for workspace folders — but says nothing else beyond what annotations and the output schema 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?

A compact, front-loaded description whose first clause names the resource and whose remainder is essential identifier-resolution detail. The closing artifact_count aside is a slight detour given an output schema exists, but nothing is 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?

A read-only, three-parameter lookup with an output schema and full schema coverage needs little more than identifier resolution rules, which are fully supplied. The main residual gap is that it never routes the agent to folder_list when a listing is actually wanted.

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 folder parameter's description is restated almost verbatim, adding no syntax, format or constraint detail beyond the schema. The workspaceId/team precedence is echoed from the schema rather than extended, 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+resource ('Get a folder's details'), which an agent can distinguish from folder_list, folder_update and folder_delete in the sibling set. It stops short of explicitly contrasting with folder_list (list vs. single-detail), 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?

The description never says when to reach for this instead of folder_list, folder_share_contents, or workspace_show, and gives no prerequisites beyond identifier resolution. The 'workspaceId when given, else team, else personal' rule is input scoping, not tool-selection 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 declare destructiveHint=true and idempotentHint=true, but the description adds meaningful behavior beyond them: the mandatory `why` for workspace folders, optimistic concurrency via expectedWorkspaceRevision that refuses with CONFLICT, and the fact that sharing widens folder visibility to external members without touching children. What remains undisclosed is reversibility and the response shape, which is acceptable given an output schema exists.

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 two main capabilities are front-loaded, and no sentence is filler, but the prose is a dense run-on of stacked colons and conditionals ('folder is its id ... or its slug: in workspaceId when given, else in team, else ...') that takes effort to parse. Information density is high at the cost of readability.

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 required-vs-optional parameters, the conditional `why` requirement, conflict handling, and the sharing side effect, all for a destructive mutation whose safety profile is already carried by annotations and whose return shape is documented by an output schema. Minor gaps: whether both audience and newSlug may be sent together, and how to undo a slug change.

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 3 is the baseline, but the description genuinely adds semantics the schema cannot express: the folder resolution chain (id of any kind, or slug resolved in workspaceId, else team, else personal) and the one-change-per-call constraint on newSlug/audience. That is real added value over field-level descriptions.

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 specific resource (folder), the two operations it performs (changing a workspace folder's audience, setting newSlug on any folder), and scopes it to one change per call. The closing sentence implies contrast with the folder_share_contents sibling, though it never names it directly.

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 conditions are given: use newSlug for any folder, audience only for workspace folders, and 'one per call' sets the call pattern. The final sentence tells an agent that sharing via audience does not propagate to child artifacts, which implicitly routes them elsewhere for that, but no alternative tool is named and no explicit 'do not use for X' is 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add real value — and it does: it discloses that secrets are never returned ('Never returns a key itself') and that browser_sessions reflects live signed-in browsers that revoking the key would sign out. That cross-tool consequence is context an agent could not infer from structured fields.

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 dense sentence, front-loaded with the resource and the field inventory, ending with the most important safety caveat. It is slightly run-on with the parenthetical definitions, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be spelled out, yet the description's field glossary resolves the ambiguity between 'agent' and 'key' that the schema alone would not. Together with the no-secret-leak note, an agent has everything needed to call and interpret it.

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 nothing for the description to disambiguate; the baseline of 4 applies. No misleading parameter claims are made.

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 the agents connected to your account') and immediately disambiguates the vocabulary by explaining that 'agents' means API keys with id, name, timestamps. It doesn't explicitly name the sibling key_revoke as the alternative, but the read/list framing makes the distinction obvious.

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 implied: this is the inventory call for inspecting connected agents. There is no explicit 'use this when' or 'do not use this for' statement, and no mention of when to prefer whoami or key_revoke instead, though the tool takes no parameters so misuse risk is low.

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. The description adds real context beyond that: the effect timing ('disconnected on its next call') and the blast radius ('every other key keeps working', self-revocation kills your own session). It does not clarify whether the key is deleted vs merely disabled, which is the one remaining ambiguity.

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, front-loaded with the action and resource, then consequences. No filler; each clause about blast radius or self-revocation earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and annotations cover reversibility and side effects. The description supplies impact scope and timing, leaving only the delete-vs-disable distinction unsettled — minor for a correctly-callable 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%, including an unusually detailed note on the optional 'why' parameter, so the schema carries the parameter burden. The description only reinforces where 'id' comes from (key_list) and says nothing about 'why'. Baseline 3 is 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 (revoke), a specific resource (one key on your account), and the id source (key_list). It is trivially distinguishable from the sibling key_list, which enumerates rather than removes.

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?

Points the agent at key_list to obtain the id and warns about the self-revocation case ('Revoking your own key (current) disconnects you'), which effectively tells the agent when this call is risky. No explicit 'do not use when' beyond that, but the routing to the sibling is 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 beyond annotations: a new address replaces and ends the old confirmation, the tool takes no code, the person enters it in their own browser, unconfirmed mailbox routes work to the person when tellPerson is on, pendingUntil semantics, and specific error codes (NO_OPERATOR, OPERATOR_AMBIGUOUS, RATE_LIMITED) with the hourly cap. Includes a security warning not to act on email contents. Much richer than the destructiveHint/openWorldHint flags alone.

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

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

Front-loads the core action and the exactly-one-of rule, with behavioral/edge detail following. Dense but every sentence carries substantive information (validity window, cap, error codes, security caution). Slightly long as a single paragraph but well organized.

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 required params, the description covers the write semantics, the out-of-band confirmation flow, pending state, failure modes, and even cites whoami for agentsUrl. Output schema exists, and it still summarizes return meaning (settings + pendingUntil). 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 coverage is 100% so baseline is 3; the description adds real value for 'address' (six-digit code emailed, 30-minute validity, counted against the person's hourly cap) and 'remove'. It doesn't mention the optional 'why' param, but the schema documents that as unrecorded.

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: 'Set or remove this agent's own email address for Tokenrip notices.' Clear scope ('this agent's own'). It doesn't explicitly distinguish itself from sibling notification_settings_set / notification_settings_get, leaving mild ambiguity about which tool to use for notification preferences vs mailbox.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the exactly-one-of pattern (address or remove: true) and the confirmation workflow clearly. Strong 'when' context is given (the person must enter the code on the Agents page), but no explicit exclusion or naming of the sibling notification_settings_set tool for non-mailbox settings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds genuine context beyond that: the built-in defaults per notification type, that per-workspace changes are reported on top of those defaults, the tellPerson fallback behavior, and that workspace rows are marked isDefault. It doesn't mention authorization requirements, but for a read-only settings fetch that's a minor 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?

The core purpose is front-loaded in the first clause and every following element describes returned content or scope. It is dense with parenthetical lists, which makes it slightly hard to scan, 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?

With an output schema present, the description needn't detail return values, yet it sketches the response shape usefully. For a fully-read-only two-param tool with complete schema coverage, the remaining undisclosed items (auth scope, paging) are largely irrelevant.

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 earns an extra point by clarifying that workspaceId augments rather than replaces the response ('With workspaceId, also each type's delivery') and by naming the isDefault marker, 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 ('Read who hears about what by email') and then enumerates exactly which settings surfaces are returned. It distinguishes the two scopes (agent vs. person) clearly. It stops short of contrasting itself with the write-side sibling notification_settings_set, so a reader must infer read-vs-write from the name alone.

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 states the default scope ('for: me, the default') and the conditional behavior of workspaceId, which implies when to pass it. However, there is no explicit when-to-use guidance against siblings (e.g., 'use notification_settings_set to change these') and no stated prerequisites or 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 declare destructiveHint=true and idempotentHint=true; the description complements this by explaining the idempotent 'setting the default again removes the change' behavior and that it returns settings after the change. It does not explicitly flag the destructive aspect beyond that, but the idempotency disclosure is genuinely value-adding context beyond the 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?

Purpose is front-loaded in the first clause, followed by parameter grouping and the timezone caution. It's dense and slightly run-on, but every clause carries actionable information without 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?

An output schema exists, and the description still notes 'Returns the settings after the change.' Combined with rich usage and behavioral notes for an 8-parameter mutation tool, nothing an agent needs to invoke 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?

With 75% schema coverage, the schema already documents most params. The description adds meaning: grouping workspaceId/type/delivery 'together', framing digestHour/timeZone as the person's (not the agent's) clock, and clarifying tellPerson activates when no mailbox exists. This meaningfully supplements the two undocumented enum params (type, delivery) which are self-describing.

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 ('Change who hears about what by email') and scopes it to notification settings, clearly distinguishing it from the sibling notification_settings_get. An agent can tell this writes settings rather than reading them.

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 documents the 'for: me' vs 'for: person' choice, the requirement to pass workspaceId/type/delivery together, and the constraint to change digestHour/timeZone 'only when the person asks, since your clock is not theirs.' It even explains that re-setting the default removes the change. This is rich when/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?

Beyond the annotations, the description discloses important mutation semantics: null clears fields, empty strings are refused, metadata replaces the stored object, website must be http/https, and visibility controls public listing. It also notes that the response is a bounded update receipt and that the profile must be read separately, all consistent with the declared destructive and idempotent 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?

The description is dense but front-loaded, moving from the endpoint and core rule to field-specific constraints and then to the response/read behavior. Every sentence carries operational value without 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?

Given eight parameters, nested metadata, an output schema, and destructive/idempotent annotations, the description provides enough behavioral context to call the tool correctly. It covers the key constraints, replacement semantics, and the need to read the profile separately, so nothing essential 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?

With 100% schema coverage, the schema already documents every parameter, so the baseline is 3. The description adds useful global semantics not fully captured by individual fields, such as 'at least one field' being required and empty strings being refused, but it does not elaborate on every parameter such as 'why' or 'alias.'

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

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

The description names a specific verb and resource ('Update your account profile') and pins it to the exact endpoint 'PATCH /v0/accounts/me.' It is clearly scoped to the caller's own profile, distinguishing it from workspace, team, artifact, and folder update siblings without needing to list them.

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 clear usage conditions: at least one field must be sent, null clears a field, empty strings are refused, and reading the profile is a separate operation. However, it does not explicitly state when not to use this tool or name a specific read sibling, leaving that inference to the agent.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real substance on top: ranking blends keywords with meaning, results carry best passages, `pending` counts chunks not yet semantically indexed, and results are paged via nextCursor. It stops short of stating anything about refusal conditions beyond the workspace-read note or about result limits, so not a 5.

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

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

Roughly 55 words, front-loaded with the one-line purpose before the scoping and ranking clauses, and no sentence is padding. It is slightly telegraphic ("mode reports how the search ranked"), which costs a little readability but not much space.

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 an 8-parameter search tool with an output schema and full annotation coverage, the description covers scoping, ranking, pending-state, and pagination — the things an agent must know before calling. Return-field detail is legitimately delegated to the output schema; only edge behavior (result caps, empty/pending-only results) is unaddressed.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine semantics: workspaceId and artifactId are two scoping routes ("or an `artifactId` in one") and nextCursor must be treated as the offset for the next page. That explains parameter interaction and pagination intent beyond the field-level 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?

Opens with a specific verb and resource ("Search readable artifacts") and immediately characterizes the ranking model (keywords + meaning, best passages), which distinguishes it from plain listing tools. It never names a sibling (e.g. artifact_list or artifact_get_content) to sharpen the boundary, so it stops 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?

"Scoped to a workspace... Elsewhere, keyword ranking" plus the artifactId-in-one mode implies when the different search modes apply, but the agent is left to infer them from behavioral prose rather than being told directly. There is no explicit when-not guidance and no alternative tool is named for enumerating or fetching a single document.

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 the safe read-only profile, yet the description adds substantial context: the file manifest is returned, filesComplete=false means the listing was truncated but those files remain readable by path, the response is one chunk as utf8 or base64 with the whole file's sha256, and the version-pinning recipe prevents mixing chunks across versions. That is exactly the kind of behaviour an agent cannot infer from structured fields.

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 the core purpose in sentence one, then the identifier rules, then the return shape, then the pagination recipe — a sensible priority order. The final sentence is long and dense with repeated 'set to' clauses, which costs a little readability, but every sentence carries functional 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 5-parameter read tool with an output schema, the description covers identifier resolution, default path, truncation caveat, encoding, integrity hash, and the pagination loop. Nothing an agent needs to call it correctly and continue a paged read 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 goes beyond per-parameter text by describing the cross-parameter contract: continuing requires skill.id with the same path, skill.version, and file.nextOffset together. It also restates the name/team resolution that the schema splits across two fields, adding a coherent joint semantic.

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?

Opens with a specific verb+resource pair ('Read a skill') and immediately scopes it ('its SKILL.md instructions by default, or any file by path'), which cleanly separates it from skill_list and skill_publish in the sibling set. The default-vs-override behaviour is stated in the first sentence rather than left to 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?

Explains the accepted identifier forms (id, page URL, name plus optional team) and the personal-vs-team resolution rule, plus exact continuation conditions while file.nextOffset is non-null. It does not explicitly name skill_list as the alternative when the agent only wants an inventory, so it stops short of full when/when-not routing.

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the result set spans both personal and team skills, each row includes version and a one-line description, and a long catalog is paged. It stops short of stating page size or ordering, so not a 5.

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

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

Three short sentences: what is listed, how it differs from the read-one sibling, then pagination — the most decision-relevant information first. No filler or repeated annotation text.

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 one-parameter read tool with an output schema and full annotations, the description supplies everything the agent needs: scope of results, per-row contents, the paging loop, and the sibling distinction. Return shape is correctly left to the output schema.

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

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

Schema coverage is 100% with a single optional offset parameter, so the schema already carries the semantics. The description's 'pass nextOffset as offset' restates the schema's own wording rather than adding syntax, defaults, or an example. Baseline 3 is appropriate when the schema does the heavy lifting.

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 the skills') plus scope (personal operator skills and team skills) and what each entry carries (one-line description, current version). It explicitly distinguishes itself from the sibling skill_get ('skill_get reads one'), so an agent can route 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?

Names the alternative tool skill_get and the condition that selects it (one skill vs. the catalog), and adds the pagination rule for long catalogs ('pass nextOffset as offset'). Nothing about when to use this versus its sibling 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?

The annotations only declare the mutation profile; the description adds the behavior that actually matters: unlisted files carry over from the current version, expectedVersion guards against clobbering a concurrent publish, and the name is owned by a team or by the operator. It also discloses a content constraint (SKILL.md must carry YAML frontmatter with name and description) that governs whether the call will succeed at all.

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 dense sentences, front-loaded with the verb and the change-set model before the version and ownership rules. Almost every clause earns its place, though the '{ path, text } for text, { path, base64 } for binary' sentence duplicates the schema's files description verbatim.

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 non-idempotent write whose annotations are generic, the description covers the mutation model, conflict handling, ownership scope, and file-content prerequisites; an output schema exists, so return values need not be explained. 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 the baseline is 3; the description earns a point by adding a validation rule not present in the schema (SKILL.md frontmatter must declare name matching the name parameter) and by restating the create-vs-update meaning of expectedVersion in operational terms. The files/removals format is largely repeated from the schema, so it is not full compensation.

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 ('Publish a new version of a skill') and immediately defines the form of the write ('as a change set'), which separates it from skill_get/skill_list without needing the schema. The scope of the change set (adds/replaces, removals, carry-over) is spelled out in the same opening sentence.

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 the agent on the key decision: expectedVersion 0 to create versus the version you read to update, plus what happens on CONFLICT. It also gives the team/no-team scoping rule. It stops short of naming an alternative tool (e.g., skill_get for reading the current version) or stating when not to publish, so it is clear context rather than a full when/when-not guide.

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 a safe, idempotent read; the description adds what is actually being counted (every kept version, table row, bundle version, and trash until purged), how workspace ownership rolls up ('a workspace counts toward its owner'), and the null-means-no-limit convention. It also discloses authorization behavior and the FORBIDDEN failure mode, which annotations cannot express.

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?

Single front-loaded paragraph that leads with purpose and permissions before enumerating counted resources. It is dense and mostly earns its length, though the run-on listing of byte categories could be trimmed since an output schema already documents the response.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't itemize return fields, yet it does so usefully; permissions and counting semantics are fully covered. The remaining gap is the undisclosed volume of 'largest artifacts' returned and any aggregation/pagination behavior for large accounts.

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 param descriptions already state slug/id, alias, membership restriction, admin-only access, and the 'Not with team' exclusion. The description largely restates those constraints; the only additive nuance is that the account param accepts an alias and that the caller's own account is the default.

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?

Opens with a specific verb+resource ('Read storage usage') and immediately scopes the targets: own account, a team, or (for admins) another account. No sibling tool covers storage accounting, and the description makes the resource unmistakable 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?

States the three usage modes (self by default, team membership, admin-only account) and the FORBIDDEN outcome for unauthorized callers, which is real routing guidance. It does not explicitly name an alternative tool to use instead, but no sibling overlaps, so the only real guidance gap is the unstated default when both params are omitted.

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 destructive and non-idempotent, but the description goes well beyond them: pre-write validation ordering, the exact error codes (INVALID_INPUT, STATE_CONFLICT, NO_TABLE_KEY, CONFLICT), the 1024-byte and lone-surrogate limits, and the fact that a table without a key refuses upsert. This is unusually rich operational detail for a write tool.

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

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

Front-loaded with the action and the bound, then layered with constraints in a logical order (validation → conflicts → upsert → alternative). It is dense and slightly run-on in the error-code sentence, but every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive multi-row write with an output schema, the description covers limits, conflict and validation outcomes, the upsert path, and the refusal cases. Nothing an agent needs to call it safely is missing; return shape is delegated to the output schema as intended.

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 genuine semantics the schema cannot express: key equality is exact-text based ('100' vs '100.0', number 1 vs string '1'), and upsert matches on the table's single unique column. The rows/expectedRevision relationship is left 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?

The first sentence gives a specific verb and resource with a hard bound: 'Append up to 1000 typed JSON rows', plus the return value ('every row ID'). It distinguishes append from update via the upsert note, but never names the sibling table_update_row, so the differentiation is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It routes between the two modes ('To update stored rows instead, pass upsert: true') and tells the agent to prefer this tool over rewriting a file for additive changes. It lacks explicit when-not guidance (e.g., when to use table_update_row or table_get_rows instead), so it stops 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.