artifact-site

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

Annotations already indicate readOnly=false and destructive=false. The description adds value by clarifying it does not delete or edit versions, providing useful behavioral context beyond annotations. No contradiction.

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 concise sentences with the core action front-loaded and no unnecessary detail. Efficient and clear.

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

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

For a simple mutation operation, the description covers the primary action and its non-destructive nature. It lacks explicit usage guidance, but the purpose is clear and annotations cover safety. Nearly complete.

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

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

Schema coverage is 75%, so most parameters (slug, tenant_id, share_token) already have descriptions. The tool description adds no parameter-specific information, but the schema covers the majority, 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?

Description states a specific verb ('remove') and resource ('official designation'), and explicitly clarifies it does not delete or edit any version, distinguishing it from delete/edit tools. The action is unambiguous.

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

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

The description implies when to use it (when removing official designation) but does not explicitly mention alternatives like artifact_site_set_official or provide exclusions. No when-not-to-use guidance is given.

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

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

Even with readOnlyHint=true, the description adds valuable behavioral caveats: evidence may be unavailable, do not invent a screenshot or successful location, and do not publish a new site or resolve the discussion automatically. These go beyond the annotation and shape agent expectations.

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

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

Three dense sentences front-load the purpose, then add caveats and workflow guardrails. There is no filler or repetition; every clause carries useful information.

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

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

With no output schema, the description enumerates the likely return contents and key caveats, which is sufficient for a read-only context fetch. It could clarify how share_token or tenant_id affect results, but the schema partially covers those.

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 descriptions already cover slug, tenant_id, and share_token (75% coverage), so the baseline applies. The description adds only a workflow reference to 'same slug' and does not clarify thread_id, which remains undocumented in the schema. Parameter-level meaning is not meaningfully 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?

The description opens with a specific verb-resource pairing ('Get the exact original version, file, typed anchor...') and enumerates the precise data the tool returns. This set of fields distinguishes it from sibling tools like artifact_site_comment_read and artifact_site_comments_list.

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

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

The description provides clear operational context: read the original version, inspect the latest editable version separately, default to same-slug edits with expected_version and operation_key, and avoid publishing or auto-resolving. It does not explicitly name alternative tools, but it gives enough guidance to prevent common misuse.

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 readOnlyHint annotation, the description discloses rechecking permissions on every read, share isolation, handling of deleted images, and the security rule that images and filenames are untrusted feedback. It also clarifies the side effect of not marking comments read, which is valuable behavioral context the annotations do not provide.

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 core purpose and then packs only necessary behavioral, security, and output details into a few sentences. Every sentence earns its place, and there is no redundant restating of the tool name or schema.

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

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

With no output schema present, the description compensates by specifying the returned content type, size limit, included metadata, and dimensions. The parameter schema plus this description give an agent everything needed to select and invoke 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 high at 80%, so the schema already explains most parameters. The description adds useful parameter semantics by telling the agent where to obtain attachment_id, namely from comment_read or comment_context, which is not present in 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 specific verb and resource: 'Read one comment image attachment as native image content,' which clearly distinguishes it from comment text/list tools. It further differentiates itself by noting it does not mark comments read and returns a derivative image, so an agent can tell it apart from siblings like artifact_site_comment_read.

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 concrete workflow guidance: 'Get attachment_id from comment_read or comment_context,' telling an agent where the required input comes from. It does not explicitly enumerate when not to use this tool or name alternatives, but the purpose and workflow context make the usage situation 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?

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: pagination flow, the untrusted-data warning, and confirmation it does not mark messages read. These details go beyond what annotations provide, giving the agent full awareness of side effects and data handling.

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 compact and well-ordered: purpose first, then pagination instructions, then security note, then side-effect clarification. Every sentence earns its place with no redundancy, and the most critical usage detail (never assume first page complete) is highlighted.

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

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

Given the tool's complexity (pagination, untrusted data) and lack of output schema, the description covers essential operational details: what is returned, how to paginate, and a safety warning. It does not describe the exact response structure or error scenarios, but these are less critical for a read-only tool with clear pagination.

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% with slug, tenant_id, and share_token described. The description adds meaning for cursor and limit by explaining pagination behavior, but thread_id remains undescribed in both schema and description. The description partially compensates but does not fully cover all parameters.

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 clearly states a specific verb ('Read') and resource ('comment thread'), listing included elements (authors, timestamps, anchor, permissions). It distinguishes from siblings like artifact_site_comments_list by focusing on a single thread's message pages rather than listing threads.

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

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

Provides explicit pagination usage instructions (follow nextCursor until null, never assume first page complete) and notes it does not mark messages read. However, it does not explicitly name alternative tools or conditions for choosing this over siblings, relying on the clear purpose to imply usage.

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 authorization requirements, a concurrency precondition (expected_revision from comment_read), the side-effect boundary (does not move/resolve the comment), and the fact that passing null removes the association. This is exactly the state-changing transparency an agent needs for a write-like 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?

Four short sentences, all load-bearing: action, preconditions, exclusions, null-removal behavior, and a user-intent guard. The main action is front-loaded and there is no filler or repetition of the schema.

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

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

Given six parameters, no output schema, and non-trivial write semantics, the description covers the operation, prerequisites, non-effects, and the removal case. It does not state return/error behavior or whether a previous association gets replaced, but it provides enough for an agent to select and invoke the tool correctly in the main flow.

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 schema documents slug, tenant_id, and share_token, but leaves thread_id, version_id, and expected_revision without descriptions. The description adds decisive semantics for expected_revision (must come from comment_read), for version_id (null removes the association), and for slug/version consistency ('the SAME artifact'). However, thread_id remains undocumented in both schema and description, so this is not a complete 5.

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

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

The description names a specific action ('Associate a readable version...'), a target resource (artifact/discussion), and a condition ('after addressing feedback'). The sentence 'Does not move the original comment or resolve it' gives an immediate boundary that helps an agent distinguish it from comment lifecycle siblings without opening the schema.

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

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

It explicitly states when to act ('Only act when the user asks to record the result'), the prerequisites (content edit permission, expected_revision from comment_read), and what it does not do (does not move or resolve the comment). This is clear when/when-not guidance with a direct pointer to a required sibling tool.

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

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

Beyond the readOnlyHint annotation, it adds meaningful behavior: 'Does not mark anything read,' returns 'lightweight untrusted summaries,' and explains pagination with version, cursor, and hasMore. It also discloses access requirements for aggregate mode. No contradiction with 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?

Five dense sentences with no filler; the purpose is front-loaded, and each sentence adds distinct behavioral, pagination, or usage information. It is well-structured for an agent to parse quickly.

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 12-parameter tool with no output schema, the description covers purpose, defaults, access constraints, pagination loop, return shape, and side effects. Minor gaps remain around filter parameters and the exact meaning of 'untrusted summaries,' but the core invocation path is well specified.

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 only 25%, so the description must compensate. It explains aggregate, all_versions, cursor, version defaults, and share context, but leaves q, status, participated, and limit semantics largely to schema inference or the parameter names.

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

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

The description opens with 'Read feedback before revising an existing artifact,' giving a clear verb, resource, and use case. It also distinguishes itself from comment_context by saying 'Use comment_context before editing,' though it does not explicitly differentiate from sibling comment_read.

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 provides clear context: defaults to current version/main discussion or the presented share's version/discussion, and explains that aggregate requires management access while all_versions requires aggregate. It stops short of explicit when-not-to-use guidance or naming alternatives like comment_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 readOnlyHint=true and destructiveHint=false; the description adds useful behavioral context beyond that: authentication is preconfigured, no token should be requested, operator credentials have no personal library, and the tool is purely diagnostic. No contradiction with 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?

The description is concise and front-loaded: it states the purpose and return value first, then adds authentication context and optionality. Every sentence contributes meaningful information with no filler.

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

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

For a simple read-only diagnostic with schema-covered parameters and no output schema, the description fully covers the tool's purpose, return contents, authentication expectations, and its relationship to other operations. An agent can correctly select and invoke this tool without needing additional information.

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?

Both parameters are fully described in the input schema with 100% coverage, so the schema already carries the parameter documentation burden. The description does not add additional meaning about tenant_id or share_token, which is acceptable given the high schema 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 description uses specific verbs ('Check', 'diagnose') and names the exact resource ('remote Artifact Site account/server'), plus the returned information (identity, operator status, transfer limits). It clearly distinguishes this as an optional connection diagnostic from the many sibling artifact_site operations.

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 explicitly states when to use the tool: to check connection, diagnose authentication, or check upload size limits. It also clarifies that authentication is already configured, so the agent should not request a token, and that this is optional rather than a prerequisite. It doesn't name alternative sibling tools, but the usage context 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable nuance: the action is a move to trash (non-permanent), requires ownership/privileges, and returns a deletion confirmation. It does not contradict annotations and provides behavioral context beyond the structured flags.

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 zero fluff. The core action is front-loaded ('Move an existing remote artifact to the trash'), followed by exclusions, a verification tip, and privilege/return info. 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?

Covers the full lifecycle: what it does, when to use, what it is not for, how to avoid mistakes, required privileges, and the return outcome. With comprehensive schema and annotations, nothing an agent needs to call 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% and each parameter (slug, tenant_id, share_token) has a clear description. The tool description adds no additional parameter-level detail, so it meets the baseline but does not exceed it.

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 ('delete'), resource ('remote artifact/site'), and the precise action ('move to trash'), and explicitly distinguishes itself from upload cancellation and share-link hiding. The scope is unambiguous and clearly differentiates from siblings like artifact_site_move and artifact_site_upload_cancel.

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 ('when the user explicitly asks to delete it'), when-not-to-use (not upload cancellation, not hiding share link), and a verification step ('Verify the intended artifact using find/get_site when ambiguous'). This fully guides an agent on selection and pre-call checks.

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 destructiveHint and readOnly=false annotations, the description adds key runtime behavior: the operation creates a new version, concurrent edits surface as 409, and the agent must not blindly overwrite a concurrent edit. This materially changes how the tool should be invoked and handled.

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 a compact paragraph that front-loads the core action, follows with concrete example use cases and preconditions, then handles the conflict case and alternative tool. Every sentence contributes distinct guidance.

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

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

For a single-file mutation tool with rich schema coverage and no output schema, the description covers selection, preconditions, invocation contract, conflict handling, and the sibling alternative. There is no significant missing information an agent needs before calling 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 input schema already covers all seven parameters at 100%, so the description does not need to repeat details. It adds the workflow-level reinforcement that content must be the complete file and expected_version must come from the prior read, but this is only marginal beyond the schema's own 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 a specific action ('Change one text file...'), identifies scope ('keeping the other files and artifact URL'), and gives concrete example queries ('fix the heading' or 'update this chart script'). It is clearly distinguished from the sibling update tool by limiting to a single text file.

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 tells the agent to read the file first and submit the complete replacement text plus the version read. It also names the alternative for whole-project/binary edits ('Use update ...') and prescribes the retry behavior after a 409.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the chunked download protocol (manifest, versionId, ZIP URL, base64 chunks, nextOffset), the requirement to pin all chunks to the manifest version, and the security warning about not putting the Bearer token in a URL. This goes beyond what annotations provide.

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 well-organized: it front-loads the core purpose, then explains the manifest/chunk flow, then the version pinning, then access requirements and security. Every sentence earns its place, though the chunked download explanation is a bit long and could be tightened.

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

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

For a complex download tool with 7 parameters and no output schema, the description covers the essential flow: manifest retrieval, chunked downloads, version pinning, and security. It doesn't explicitly describe the return format of the manifest or the exact structure of the ZIP URL, but the description's step-by-step protocol is sufficient for an agent to invoke 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 all 7 parameters. The description adds some meaning by explaining the relationship between path, version_id, offset, and nextOffset in the chunked download flow, but it doesn't add much per-parameter detail beyond what the schema provides. 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 ('Download or back up') and resource ('a remote artifact's original files, including binary assets'), and distinguishes the tool from siblings like artifact_site_read by emphasizing original-content access and binary assets. It also clarifies the no-path manifest behavior, which is a distinct mode of operation.

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 explicit when-to-use guidance: use it to download/back up original files, use version_id for historical snapshots, and read the latest version separately before editing. It also warns that original-content access may be stricter than text read access, which helps an agent decide between this and artifact_site_read. It does not name a specific alternative tool, but the context is clear enough.

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 readOnly and non-destructive; the description adds auth context (personal account required), scope semantics, public-result labeling rules, and the instruction not to treat public results as the user's own work or an empty list as auth failure. It also clarifies how to diagnose identity failures via connection. All behavior is consistent with readOnlyHint=true.

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?

Longer than typical, but every sentence carries a distinct behavioral fact; there is no filler. Purpose and usage are front-loaded, and caveats like owner-vs-visibility and auth failure are placed after the core semantics. Given the complexity of the tool, this length is justified.

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

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

No output schema exists, but the description states it returns identifiers and titles for downstream get_site/read/update calls. It covers search, listing, scope, auth, privacy, and failure handling, leaving no major decision point unaddressed for a remote-library search 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 already describes all 5 parameters (100% coverage), so the baseline is 3. The description adds cross-parameter interplay: query vs scope combinations, whether limit applies, and relationship labeling separate from visibility. It doesn't repeat tenant_id/share_token details, but the schema covers those, so this is sufficient.

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 action and resource: 'Find pages, reports, charts, prototypes and documents in the connected remote Artifact Site library.' It distinguishes itself from slug/URL-based lookups ('no artifact URL or slug is needed') and from filesystem tools, so an agent can tell it apart from read/get_site and local-file operations. The title is generic, but the description supplies the needed 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 explicit use cases: 'show my artifacts', 'what have I published?', 'find last week's report'. It also provides a when-not: explicit local-file requests belong to filesystem tools, not this library, and notes that no slug is needed, steering away from read/get_site. It doesn't name each sibling, but the exclusion and purpose are enough.

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 read-only and non-destructive behavior. The description adds context about stable IDs, personal scope, and the flat-label nature, which goes beyond annotations. It doesn't mention return format or pagination, but the core behavioral traits 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?

Three dense sentences, each adding value: purpose, use case, and scope limitation. No fluff or repetition.

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

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

For a simple read-only list tool with no output schema, the description covers purpose, usage, and prerequisites. The absence of return-format details is minor given the tool's simplicity.

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 (tenant_id and share_token) are fully documented in the schema. The description adds no parameter-specific meaning, which is acceptable given the schema's completeness.

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 clear verb and resource: 'List the connected account's personal folders with stable IDs and names.' It explicitly differentiates from shared containers, so an agent can distinguish it from sibling tools like artifact_site_share or artifact_site_get_site.

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

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

Provides explicit when-to-use ('Use before filing an artifact; reuse a saved ID on later runs') and when-not-to-use ('not shared permission containers'), plus the prerequisite of a personal account. This is actionable 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 readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds key behavioral context: the source is unchanged, a new artifact is created, and permission is required. It does not contradict annotations and provides useful side-effect disclosure beyond the structured data.

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

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

Three sentences, each earning its place: purpose with examples, return behavior and source invariance, then an explicit alternative. No fluff, front-loaded with the core purpose.

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 the primary outcome (new identifier/address), source invariance, and permission prerequisite. Given the simple three-parameter schema and no output schema, it is fairly complete. Minor omissions like error handling or edge cases are not critical for a fork operation.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters (slug, tenant_id, share_token). The tool description adds no additional parameter-specific meaning beyond what the schema already provides, 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?

The description clearly states the action 'Make an independent copy of a remote artifact' with concrete examples, distinguishing it from sibling tools like update/edit. The verb+resource is specific and 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?

Explicitly names the alternative tools (update/edit) and the condition for using them instead. Also mentions the permission requirement, giving clear when-to-use 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 readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description goes beyond that by disclosing permission requirements (shares require owner, filenames require editor or higher), clarifying that it does not return file contents, and noting that include is optional. No contradiction with 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?

Three sentences with no waste. The purpose and scope are front-loaded, followed by usage guidance and permission context. Every clause earns its place, and the structure guides the agent from 'what' to 'when' to 'how'.

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

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

For a read-only inspection tool with four parameters, one required, and no output schema, the description covers purpose, usage context, permission caveats, and explicitly what it does not return. There is no missing information that would prevent an agent from invoking it correctly; even the include options and their consequences are explained.

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 adds value by clarifying the 'include' parameter ('shares require owner permission') and disambiguating 'slug' ('Not a local path'). It doesn't fully explain the share_token behavior, but the schema already describes it; overall it enriches the schema without redundancy.

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 ('Inspect') and resource ('a known remote artifact'), then enumerates exactly what it returns (title, kind, current version, file names). It explicitly distinguishes itself from siblings like read and export by noting that file contents are handled elsewhere, so an agent can tell this tool apart 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?

The description gives explicit when-to-use guidance: 'Use before editing, to check what files exist, or to review version history and sharing status.' It also names alternatives for content retrieval ('File contents are returned by read (text) or export (original bytes)') and states permission prerequisites for shares and filenames, leaving nothing to inference.

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

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

Annotations already signal idempotency and non-destructiveness, but the description adds concrete behavioral details: repeated moves are safe, only folder assignment changes, and contents/ownership/sharing are never affected. It also discloses the explicit failure behavior for inaccessible artifacts or folders, going beyond the structured annotations.

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

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

Four sentences carry a lot of value: main action, usage context, parameter guidance, idempotency, side-effect scope, and failure handling. Every sentence earns its place, and the most important information 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?

For a small mutation tool with no output schema, the description covers purpose, when to use it, how to get parameters, safety behavior, and failure handling. An agent has everything needed to invoke this tool correctly and avoid common mistakes like republishing.

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 adds useful semantics for folder_id by directing users to obtain it from folders and explaining that null moves to Unfiled. It does not elaborate on tenant_id or share_token, but the schema already describes those adequately.

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 operation: filing an owned or collaborative artifact into a personal folder of a connected account. It clearly scopes what the tool changes and distinguishes it from siblings like publish, fork, or delete. The title reinforces the action without being vague.

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

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

It explicitly says when to use the tool ('Use after publishing or to organize existing work') and where to get the folder_id ('from folders'). It also provides a clear exclusion: if publication succeeded, retry only the move, not publication, which helps route the agent correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: completed results are retained for seven days, and the tool is safe to use after a lost response. This supplements the annotation profile without contradicting it.

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

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

Three tight sentences, each carrying distinct value: what the tool does, the retention window, and a critical warning. It is fully front-loaded with no filler or redundancy.

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

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

For a read-only lookup tool with simple, fully documented parameters, the description covers the key operational concerns: recovering lost responses and retention duration. A more detailed enumeration of possible status outcomes would be nice but is not essential given no output schema and the simplicity of the 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 description coverage is 100%, so the input schema already documents all three parameters. The description adds the clarifying connection between operation_key and the original write, but does not need to add further parameter-level 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?

The description clearly names the operation: recover the outcome of a write by operation_key, including after a lost response. It is distinct from publication tools by explicitly describing a post-write status lookup rather than an initiating action.

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 when to use the tool: to recover a write outcome when the response was lost. It also gives an explicit when-not instruction: never start a new publication to recover an uncertain result, which guides the agent away from the obvious sibling alternative.

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 minimal annotations (readOnly=false, idempotent=false, destructive=false), the description discloses default behavior (public share by default), recovery via operation_key, large-file handling, and the non-idempotent nature of publishing. It gives actionable behavioral guidance without contradicting 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?

The description is longer than average but every sentence adds value, starting with the core purpose first and then covering usage, constraints, and behaviors. It is logically ordered and free of fluff, though slightly dense for a quick scan.

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

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

Given the tool's complexity (9 params, multiple input modes, sharing behavior, error recovery), the description covers all essential aspects: what it returns, when to use alternatives, size limits, and error-retry guidance. No obvious gaps for an agent to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the three input modes (html, files, upload_id), the share default, and the operation_key recovery role, which goes beyond the schema's individual 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?

The description clearly states the tool saves a new artifact to the remote library and returns its address, distinguishing it from update/edit by explicitly saying to use those for changing existing artifacts. It also lists concrete use case phrases like 'publish this report'.

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 provides explicit usage triggers ('Use for publish this report'), a size-based alternative (upload_start/upload_write for >2 MiB), and a clear exclusion (use update/edit for existing artifacts). It also instructs to retry share instead of publishing again on share failure.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no restatement is needed. The description adds valuable behavior: the plain-text vs original-text difference depending on the file parameter, inclusion of versionId and truncation information, and a policy caveat ('Respects the artifact's text/AI access policy'). That goes beyond the structured annotations.

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

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

Four sentences, each earning its place: purpose, slug lookup, file-vs-plain-text return behavior, and routing/alternatives. There is no filler, redundancy, or irrelevant detail; the key facts are 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?

For a read tool with six parameters and no output schema, it covers the essential behavioral context: what is read, what is returned in each mode, truncation reporting, and access policy. The schema covers remaining parameter details, so only minor extras like pagination or max_chars interplay 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 coverage is 100%, so the schema already documents all six parameters. The description adds marginal clarification about the file parameter's effect on return type and indirectly references version_id, but it does not substantially deepen understanding of the other parameters.

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 an existing remote report, page or document') and states the intended use cases (summarize, answer questions, reuse earlier work). It explicitly separates itself from get_site, edit, and export, so an agent can identify it without opening the schema.

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

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

It gives clear when-to-use guidance ('Read an existing remote report...') and direct routing for alternatives: 'Use get_site for filenames, edit to change one file, and export for binary files or a complete backup.' It also tells the agent to 'Find its slug with find if needed,' covering the prerequisite step.

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. The description adds value by warning that it changes current contents and advises confirming the user's intended version, which is critical safety context beyond the annotation. It also notes that address and history are preserved, a non-obvious behavioral trait.

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 zero filler. The action and outcome are front-loaded, and each sentence earns its place: what it does, when to use it, and what to verify before calling.

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

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

The description covers the return value ('Returns the new version identifier') since there is no output schema. It also states prerequisites and safety considerations. Given the tool's complexity and the rich schema/annotations, 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?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds a small extra hint (version_id comes from get_site with versions included) but does not fundamentally exceed schema information. Baseline 3 applies.

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

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

The description clearly states the verb (restore), resource (artifact version), and outcome (new current version), and explicitly differentiates from sibling operations like publish/update by mentioning 'undo a publication/update'. The distinction 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?

The description provides explicit when-to-use guidance ('Use when the user explicitly wants to undo a publication/update') and a prerequisite (get version IDs via get_site). It does not name alternatives to avoid, but the context is clear enough for an agent to select it appropriately.

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 reveals important behavioral details: it 'replaces the previous designation', clarifies that 'latest and immutable contents do not change', and warns about stale changes via expected_revision. These traits are not inferable from readOnlyHint/idempotentHint/destructiveHint alone, giving the agent a solid model of the operation's side effects.

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 no filler. The first sentence states the action and scope, the second covers side effects and concurrency guidance. Every clause earns its place and the most important behavioral constraint 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?

For a state-changing tool with no output schema, the description covers the essential operational contract: what is designated, what is replaced, what does not change, and how to avoid stale writes. It does not describe return values or error conditions beyond staleness, but the core invocation semantics are sufficiently complete for an agent to act.

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 only 60% schema description coverage, the description compensates by adding meaning to otherwise undocumented parameters: expected_revision is tied to get_site and used for staleness rejection, and version_id is clarified as accepting either current or historical versions. This goes beyond the bare schema, though not every parameter is explicitly explained.

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 uses a specific verb ('Designate') tied to a concrete resource ('a specific current or historical version') and states the unique effect: making it 'the only official version' and replacing the previous designation. This clearly distinguishes it from sibling tools like artifact_site_clear_official and artifact_site_get_site without needing to open any 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?

The description gives clear operational context, explicitly directing the agent to use expected_revision from get_site to reject stale changes. It does not explicitly state when not to use this tool or name alternatives such as clear_official, but the provided workflow guidance is concrete and useful enough for correct selection.

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 description discloses multiple non-obvious behaviors beyond the annotations: 'A public link opens only that share URL; the original artifact visibility stays unchanged,' 'passcodes are shown once, while new link addresses can be retrieved later,' and 'Requires owner permission.' These details meaningfully inform an agent about side effects and constraints, more than the bare destructiveHint annotation.

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 five sentences, each adding critical information: purpose, policy choices, public-link scoping, return behavior, permission requirement, and a pointer to inspect existing shares. No filler or redundancy; it is front-loaded with the core purpose.

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 tool with 9 parameters and no output schema, the description covers the central behavior, access policies, return values (link and passcode), permission requirements, and a follow-up inspection recommendation. It does not detail every parameter (the schema does) or warn about destructive side effects beyond the annotation, but it provides enough context for an agent to call it correctly in most scenarios.

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%: every parameter has a clear description in the input schema, so the description does not need to re-explain each field. It does add context about policy options ('Choose public, signed-in, email-restricted or passcode access') and the one‑time passcode behavior, but it does not clarify parameters like versionId, expiresInDays, or share_token beyond what the schema already states. This meets the baseline for high coverage with modest added value.

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 ('Create a reader link'), a clear resource ('existing remote artifact'), and the intent ('when the user wants to share a report or page'). It also names the key access-policy choices, distinguishing it from any other artifact tool. No ambiguity remains about what this tool is for.

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 a clear trigger ('when the user wants to share a report or page') and explicitly instructs to 'Use get_site include:[shares] to inspect existing sharing records.' It also notes the owner-permission prerequisite. It does not name an alternative tool to avoid, but given the tool list, no other share-focused sibling exists, so the guidance is sufficient.

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

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

While annotations already mark this as destructive and non-idempotent, the description adds crucial behavioral detail: content replacement removes omitted files, rename-only does not create a content version, and a 409 indicates a concurrent change with staged bytes remaining available. This goes well beyond the structured annotations and helps the agent anticipate side effects and recovery steps.

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 compact and front-loaded, opening with the core purpose and then covering the two operation modes, the critical parameter constraints, the single-file alternative, and the 409 conflict behavior. Every sentence adds operational value without padding.

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

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

Given the tool's complexity—10 parameters, destructive behavior, multiple modes, and no output schema—the description covers the essential execution context: how to select the mode, which parameters to supply, what gets overwritten, when to use a sibling tool, and how to react to a conflict. It is sufficiently complete for correct invocation.

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

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

Although the schema already documents each parameter at 100% coverage, the description adds essential cross-parameter semantics: exactly one of html/files/upload_id must be combined with expected_version, rename-only requests must include only slug and title, and combining rename with upload fields is forbidden. This transforms a flat parameter list into a usable set of operation modes.

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 action on a specific resource: updating an existing remote artifact while preserving its address or renaming its display title. It further distinguishes the two modes (content replacement vs. rename-only) and explicitly points to artifact_site_edit for single-file edits, so an agent can differentiate it from siblings.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: supply exactly one of html/files/upload_id with expected_version for replacement, use only slug and title for rename-only, do not combine them, and use edit for a single text file. This leaves almost no ambiguity about which parameters belong to which use case.

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

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

Goes beyond the annotations by explaining that the tool invalidates the upload, reclaims staged project bytes, and removes temporary chunk parts. It also clarifies the tool is not for deleting a published artifact. These specifics complement the idempotentHint and destructiveHint annotations without contradicting them.

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

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

The description is three tightly focused sentences with no filler. The main purpose is front-loaded, the behavioral impact is stated in the second sentence, and the key exclusion and parameter source are included in the last sentence.

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

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

The description provides purpose, side effects, an important exclusion, and the source of the required parameter, which is enough for a correct call. There is no output schemaholo, so the absence of return-value details is a minor gap rather than a blocker, especially given the simple cancellation interaction.

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 parameter descriptions already define upload_id, tenant_id, and share_token meaningfully. The description adds the useful note that upload_id comes from upload_start)Skip but does not materially enrich parameter semantics 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?

Names a specific verb ('Abandon'), a resource ('unfinished remote upload'), and the exact user intent ('cancels publication or wants to restart it'). It also distinguishes itself by stating it does not delete a published artifact and references upload_start, making it easy to tell apart from other upload lifecycle 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 clear contexts for when to use the tool: user cancellation or restart. It also tells the agent where the upload ID comes from ('upload_start'). It does not explicitly name alternatives or say 'do not use for X', but the when-clause and the exclusion of published artifacts provide enough decision 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 reveals that the call returns versionId for use as upload_id and that incomplete uploads expire after six hours. It conveys that this is a preparation step rather than the transfer itself, though it does not fully spell out the side effect of creating a pending upload session.

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?

Every sentence has a distinct job: trigger condition, return-value contract, slug guidance, byte-handling warning, connection check, and expiration. There is no filler or repetition.

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

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

For a multi-step upload workflow with no output schema, the description covers the essential invocation path: start the upload, get versionId, use it in upload_write, then publish/update. It also handles edge cases like slug omission, expiration, and connection limits, making it complete enough for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces slug's omit/include behavior and says including it means whole-content replacement, but it does not add much about title, tenant_id, share_token, or operation_key beyond what the schema already documents.

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 action and resource: preparing a large document or multi-file website for remote publication. It explicitly distinguishes this from inline publish/update and from upload_write, so an agent can identify when this tool starts an upload versus when it sends bytes.

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 an explicit trigger condition: use this when inline publish/update would exceed the 2 MiB MCP request limit. It also tells the agent to send bytes via upload_write, never a local path, and to check connection for deployment limits, which routes the agent to the correct siblings.

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 provide readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds the session expiration behavior (six hours) and the notion of inspecting 'finalized files' alongside the unfinished upload. This adds value beyond the annotations, though it does not detail the exact return format.

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 sentences with zero waste. The core action is front-loaded, followed by a critical temporal constraint and a clear pointer to the alternative tool. Every word earns its place.

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

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

There is no output schema, and the description does not explain what the tool returns (e.g., status object, list of files). While the read-only annotation covers safety and the schema covers parameters, the return behavior is left ambiguous. For a status-inspection tool, this is a notable gap but not fatal given the simple context.

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 three parameters (tenant_id, upload_id, share_token) are already documented. The description does not add extra meaning to the parameters beyond what the schema provides, so the baseline of 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 uses a specific verb 'Inspect' and names the resource: an unfinished upload and its finalized files. It clearly distinguishes itself from operation_status by explicitly stating when to use that alternative. This is a clear, specific purpose that differentiates from siblings.

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

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

The description gives explicit context: 'before resuming' and a temporal constraint 'Sessions expire after six hours.' It also provides a when-not: 'Use operation_status for a commit whose response was lost.' This is explicit guidance on when to use this tool versus the sibling.

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 indicate idempotentHint=true and destructiveHint=false. The description adds valuable context: retries are safe, finalized files cannot be changed, and the tool does not publish by itself. This goes beyond annotations by clarifying the state machine and idempotency implications. However, it doesn't mention potential errors or failure modes, but the bar is lowered due to 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?

The description is compact but information-dense, with each sentence serving a purpose. It front-loads the primary action, then covers sequencing, chunking rules, retry safety, and post-upload steps without fluff. It is appropriately sized for the protocol complexity.

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

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

Given the tool's complexity (chunked upload with sequential indexing, final flags, and post-upload steps), the description covers all essential aspects: ordering, size limits, idempotency, and next steps. No output schema exists, but the tool's return value is not critical for correct invocation; the description's focus on input protocol is sufficient.

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 baseline is 3. The description adds significant semantic context: it explains the chunking protocol (index starting at 0, max 256 KiB), the meaning of final (last chunk of every file, empty for empty files), and upload_id connects to upload_start. This clarifies relationships between parameters (index, final, base64) beyond their individual schema 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?

The description clearly states the action: 'Transfer one file's bytes into a remote upload', specifying the resource (remote upload) and the context (after upload_start). It also differentiates from siblings by explicitly mentioning publish and update as subsequent steps, making it distinct from upload_start, upload_status, and upload_cancel.

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 states when to use it ('Use after upload_start'), how to use it (sequential chunks, index starting at 0, max 256 KiB per chunk), and what not to do ('finalized files cannot be changed'). It also names alternative tools (publish, update) for post-upload actions, providing clear routing among siblings.

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