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

Because no annotations are provided, the description carries the full burden of behavioral disclosure. It does disclose the key non-destructive trait (documents accessible by URL) and the effect on listings, but leaves ambiguity about whether the project itself disappears from project listings and does not mention reversibility despite the sibling unarchive_project.

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 long, front-loaded with the purpose and a clear behavioral effect. Every word earns its place, with no redundancy or fluff.

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

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

For a simple one-parameter tool with no output schema, the description covers the primary behavior but leaves gaps: it does not fully clarify the project's own visibility status or whether the action is reversible. It is adequate but not comprehensive.

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

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

Schema description coverage is 0%, and the description does not explain that the required 'id' parameter identifies the project to archive. While the parameter's meaning is inferable from the tool name, the description adds no explicit semantic value 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 clearly states 'Soft-archive a project' with a specific verb and resource, and explains the key distinction from deletion: documents remain accessible by URL. This differentiates it from sibling tools such as delete_document and unpublish_document.

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 for when to use the tool—when a project should be hidden from listings but remain accessible—and implies this is a non-destructive alternative. However, it does not explicitly name alternatives like unarchive_project or state when not to use it.

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

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

With no annotations, the description carries the burden of disclosing behavior. It states the tool performs a check and returns { available, suggestion? }, which implies a read-only operation. However, it does not clarify what 'available' means (e.g., case sensitivity, normalization, or whether the slug is checked across all workspaces). The return shape is helpful but behavioral nuance is minimal.

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 sentence conveys the action, scope, and return shape without redundancy. The information is front-loaded and 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?

This is a simple single-parameter check tool. The description provides the return shape, which is important since there is no output schema. Given the low complexity, the description is nearly complete, though it could mention what 'suggestion' contains. Overall, it covers the essential 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 coverage is 0% and the description does not add detail about the 'slug' parameter beyond what the name implies. It does not specify allowed characters, case sensitivity, or required format. The description only restates 'project slug' without further semantic 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 starts with a specific verb 'Check' and identifies the resource 'project slug' with a clear scope ('in the PAT's workspace'). It also mentions the return shape, distinguishing it from sibling tools like create_project or rename_project_slug.

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 purpose implies it is a pre-check before creating or renaming a project, but the description does not explicitly state when to use it versus alternatives like create_project or rename_project_slug. There is no direct guidance on exclusions or prerequisites.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the authentication binding ('active PAT'), the return value details, the draft nature of the document, and the default placement behavior. It also implies that the operation is additive (create) without destructive side effects, which is appropriate for a create 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?

The description is concise (three sentences) and front-loaded with the core purpose. Each sentence adds distinct value: return behavior, content flexibility, and placement guidance. No redundant or filler language is present.

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 create tool with six optional parameters and no output schema, the description covers essential context: return values (id, slug, edit URL), the draft status, the ability to defer content, and default placement. This is sufficient for an agent to invoke the tool correctly without additional documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that project_id/folder_id control the destination location and that content can be omitted for later update. This enriches the parameter semantics, though other parameters like format and slug are already well-covered by 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 a specific action ('Create a new draft document'), names the resource ('uselink workspace') and binding ('active PAT'), and clearly distinguishes from sibling tools like uselink_update_document or uselink_publish_document. It also mentions the return of id, slug, and edit URL, reinforcing the tool's core function.

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 guides when to use this tool versus the alternative by noting that content can be omitted and added later via uselink_update_document. It also explains how to direct placement via project_id/folder_id and the default fallback, giving clear when-to-use and when-not-to-use context.

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

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It mentions slug auto-generation and root vs. nested creation, but these are largely restatements of schema descriptions. Missing are details on permissions, reversibility, error behavior, or response format, which is a significant gap for a mutating create operation.

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, consisting of two sentences that front-load the primary purpose. Each sentence adds a specific usage or behavioral detail without any 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 straightforward create operation, the description covers the core action, nesting behavior, and slug auto-generation. While it omits permissions and error conditions, the simplicity of the tool and absence of an output schema make this an acceptable level of completeness. A short note on side effects would improve it slightly.

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 60%, with name and project_id lacking descriptions. The description clarifies parent_folder_id and slug behavior, but since those are already documented in the schema, it adds minimal new meaning. Name and project_id are left to implicit understanding, though the overall purpose makes them obvious.

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 'Create a new folder inside a project,' clearly identifying the action (create) and resource (folder) within a project scope. This distinguishes it from sibling tools like update_folder, delete_folder, and create_document.

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 usage context, explaining how to create at the project root by omitting parent_folder_id and how to nest by passing a folder id. However, it does not explicitly mention alternatives or when not to use this tool, so it misses explicit exclusion guidance.

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

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

With no annotations, the description must carry the behavioral burden. It discloses important behaviors (workspace inference, slug derivation) but omits details like permissions, success/error responses, or any side effects. It adds some value but leaves gaps for a create operation.

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 communicate purpose and key nuances without wasting words. Front-loaded with the main action, then clarifying details.

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 simple tool (2 params, no output schema), the description sufficiently explains the creation behavior and edge cases around workspace and slug. It lacks a mention of the return value or error conditions but remains mostly complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description says slug is derived from name, which is already in the schema. It adds no additional parameter semantics beyond what the schema already provides.

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 'Create a new project' with a specific verb and resource, and details workspace/slug behavior. It distinguishes from sibling project tools like list_projects or update_project by focusing on creation.

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 on workspace inference (PAT-scoped vs personal) and slug auto-generation, helping the agent understand when this tool is appropriate. However, it does not explicitly name alternatives or exclusions, so no when-not-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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states a key side effect: "the document is removed and the public URL stops working." This communicates the destructive, immediate consequence. However, it does not explicitly mention irreversibility or whether associated data (comments, assets) is affected, which would add further transparency.

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 concise sentences that front-load the main action: "Delete a uselink document." The second sentence provides a useful impact detail without redundancy. Every word earns its place, making it highly efficient.

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 simplicity (one required parameter, no output schema, no annotations), the description is sufficiently complete. It explains the operation and its primary consequence (public URL stops working). It could optionally mention irreversibility or error cases, but for a basic delete tool, the information is adequate.

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 covers the sole parameter 'id' 100% with a description of 'Document UUID'. The description does not add meaning beyond the schema; it merely restates that the document is deleted. Since the schema already handles parameter semantics, 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 and resource: "Delete a uselink document." This clearly distinguishes it from sibling tools like uselink_read_document, uselink_create_document, and uselink_update_document by naming the delete operation 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?

There is no explicit guidance on when to use this tool versus alternatives. The description only states what happens (document removed, URL stops working) but does not mention prerequisites such as unpublishing the document first, nor does it contrast with other deletion-related operations. The absence of usage context leaves the agent without clear direction.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully discloses a non-obvious side effect: documents are moved to project root rather than deleted. However, it does not address what happens to subfolders or whether the deletion is reversible, which leaves some gaps.

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 concise sentences. It front-loads the primary action and immediately adds a critical caveat, with no superfluous words. 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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers the main behavior and the most important nuance about contained documents. It could be more complete by mentioning subfolders or permanence, but for a delete-folder operation it is largely 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?

The input schema has one parameter (id) with 0% description coverage, and the description does not explicitly explain that 'id' refers to the folder being deleted. Although the parameter name and format are self-explanatory, the description adds no value beyond the schema, so it fails to compensate for the low 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 clearly states the action 'Delete a folder' with a specific resource. It also distinguishes itself from sibling tools like delete_document by explicitly noting that documents inside are NOT deleted and are moved back to the project root.

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 a clear use case: deleting a folder while preserving its documents. However, it does not explicitly mention when to use this tool over alternatives or provide exclusions, leaving the usage guidance implicit rather than direct.

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?

Since no annotations are provided, the description carries the full burden. It indicates a read-only operation via the verb 'List' and specifies the return type (images, files). However, it does not disclose pagination behavior (limit/offset), return format, or any potential side effects. For a list operation, this is adequate but not rich.

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 single concise sentence, front-loaded with the verb and resource. It earns its place, but it could be slightly more informative without bloating. It is not overly verbose, scoring well on conciseness, though not perfect due to missing parameter details.

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 no output schema, no annotations, and three parameters. The description is too minimal to be complete: it does not mention pagination (limit/offset), the requirement for document_id, or what the response structure looks like. Given the tool's moderate complexity, the description leaves many important operational details 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?

The schema has 0% description coverage for its three parameters. The description adds minimal meaning: it clarifies that assets are 'attached to a document,' which maps to the required document_id parameter. However, it does not explain limit/offset or their roles, so the description fails to compensate for the complete lack of 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 tool's function: 'List assets (images, files) attached to a document.' It uses a specific verb ('List'), a clear resource ('assets'), and a qualifier ('attached to a document') that distinguishes it from sibling tools like uselink_list_documents (lists documents) and uselink_list_comments (lists comments).

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 usage: it is for retrieving assets belonging to a specific document. However, it provides no explicit guidance on when to prefer this over alternatives (e.g., uploading assets with uselink_upload_asset) or any exclusions. The context is implied but not spelled out.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions 'threaded' but does not explain ordering, whether resolved comments are included, pagination behavior, or what fields are returned in the response. The one-word hint about structure is insufficient.

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 single sentence with no fluff, directly stating the core function. It is concise and front-loaded, but it sacrifices useful substance for brevity, which prevents a perfect score.

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

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

Given no annotations, no output schema, and 0% parameter descriptions, the description is far too minimal. An agent cannot determine return format, pagination behavior, or how 'threaded' affects the response, making the tool poorly specified for reliable 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 0%, so the description must compensate. It implies document_id's role via 'on a document' but offers no explanation of limit or offset, which are standard pagination parameters but still undocumented. The description adds minimal value beyond 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 clearly states the tool lists threaded comments on a document, using the specific verb 'list' and a resource ('threaded comments on a document'). This distinguishes it from comment-writing tools like uselink_reply_comment and document-read tools like uselink_read_document.

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

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

There is no guidance on when to use this tool versus alternatives such as uselink_reply_comment or uselink_resolve_comment. The description does not mention prerequisites, typical workflows, or why one would choose this over related comment operations.

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

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

No annotations are provided, so the description carries the disclosure burden. It adds useful context by stating the return fields (id, title, slug, status, timestamps) and the binding to the active PAT. However, it omits pagination behavior, sorting, and explicit read-only safety confirmation, leaving gaps for a list operation.

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 concise sentences, front-loaded with the primary action and output fields. Every word adds value, with no fluff or redundant repetition of the tool name.

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

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

The description covers the core purpose, return fields, and filtering capabilities. However, with no output schema and no annotations, it omits essential details like pagination behavior, limit/offset semantics, and does not clarify the relationship to uselink_search_documents. It is adequate but has clear gaps for a list 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 50%, with limit and offset lacking descriptions. The description mentions filtering by status and free-text search, but these are already described in the schema. It does not clarify the default or maximum for limit, nor the meaning of offset, so it fails to compensate for the undocumented 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 the tool lists documents in the uselink workspace with a specific verb and resource. It lacks explicit sibling differentiation, as the sibling uselink_search_documents may also list/search documents, so it doesn't distinguish when to prefer one over the other.

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 no explicit guidance on when to use this tool versus alternatives like uselink_search_documents. It implies usage for listing and filtering, but does not state exclusions or when a different tool should be chosen.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns folders plus a parent_breadcrumb for navigation, which is useful behavioral context. It also clarifies the optional-parent behavior. While it doesn't explicitly state read-only, the verb 'list' implies no 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 fluff. The first sentence states the main action upfront, and the second explains the conditional parameter. Every clause earns its place, making it highly concise and well-structured.

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 simplicity (2 params, no output schema), the description covers the essential semantics: the project context, optional parent ID, and the returned data including parent_breadcrumb. It lacks mention of pagination or error handling, but for a straightforward list operation, it is sufficiently 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 50%, with only parent_folder_id having a description that matches the tool description's explanation. The tool description adds meaning to project_id by implying it identifies the project, but this is not deeply detailed. For parent_folder_id, it repeats the schema description rather than adding new info.

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 starts with 'List folders in a project,' which clearly states a specific verb and resource. It distinguishes itself from sibling tools like uselink_list_documents and uselink_list_assets by focusing on folders. The additional detail about parent_folder_id and root/child listing further clarifies the scope.

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 explains when to pass parent_folder_id (to list children) and when to omit it (to list root folders). This provides clear context for parameter use. It does not explicitly mention alternatives, but the sibling tool names make the purpose obvious.

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

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

With no annotations, the description carries the burden. It discloses token-scope behavior and return fields, which is useful. However, it omits default behavior for archived projects (include_archived defaults to false) and pagination semantics, leaving some behavioral gaps.

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, directly states action and key outputs, no fluff. Front-loaded with the primary 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?

The description reports return fields (id, name, slug, default flag, archive state, document count), which is helpful given no output schema. However, it lacks parameter semantics and default filtering behavior, making the tool less complete than desired.

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 description provides no explanation of the three parameters (limit, offset, include_archived), and schema coverage is 0%. The description's mention of 'archive state' in returns does not clarify the include_archived parameter. This fails to aid the agent in parameter usage.

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 the verb 'List' with resource 'projects', clearly identifying the operation. It also distinguishes from sibling read_project (single project) by describing scope behavior for different token types, making the purpose 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 sets a clear context: when you need to list projects visible to the active PAT, use this tool. It also explains token scoping, but does not explicitly compare to alternatives or state when not to use it.

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

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

With no annotations, the description carries full burden. It clearly implies a mutating action ('move') and discloses the default folder behavior. However, it does not mention possible side effects, permission requirements, or what the response contains.

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 primary purpose, followed by parameter guidance. No wasted 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?

The description covers the core action and the main parameter behavior. However, without an output schema or annotations, it omits return value, error conditions, and constraints (e.g., whether folder_id must belong to the target project). This is adequate but not fully complete.

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

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

Schema description coverage is low (33%), but the description compensates by explicitly stating project_id is required, folder_id is optional, and omitting folder_id lands at the project root. This adds meaning beyond the schema, though document_id is not discussed (it is self-evident).

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+resource: 'Move a document into a different project and/or folder.' This clearly differentiates from sibling tools like move_folder or move_project, and specifies the destination scope.

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 clear context: move a document between projects/folders. It explains the required project_id and the optional folder_id, including the default behavior of landing at the project root. However, it does not explicitly exclude alternatives or mention when not to use the tool.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It explains the parameter-dependent behavior but omits side effects (e.g., impact on child folders, permission requirements, error conditions). This is a significant gap for a mutation 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?

A single, front-loaded sentence with zero filler. It conveys the action, the key parameter behavior, and the two usage scenarios economically.

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 only two parameters and no output schema or annotations, the description covers the core action and both parameter modes. It does not explain return values or side effects, but the tool is simple enough that this is a minor omission rather than a critical gap.

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

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

Schema description coverage is 50%, and the description redundantly states what the schema already says for parent_folder_id ('root if omitted'). It adds the functional framing of re-parenting but does not substantially expand on parameter 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 opens with a specific verb + resource ('Re-parent a folder'), clearly distinguishing this from sibling tools like uselink_move_document or uselink_update_folder. It unambiguously states what the tool does.

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 on how to use it for two scenarios (move to root vs. nest under a folder), but it does not explicitly mention when not to use it or name alternatives. This is clear, practical guidance without formal 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly indicates a mutation but fails to mention potential side effects (e.g., whether the project is removed from its previous location, if any), permission requirements, reversibility, or what the response contains. The brevity leaves the agent uninformed about outcomes.

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 single, well-structured sentence that immediately conveys the core operation. It is concise with no redundancy or filler, and every word adds value.

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 annotations, no output schema, and only two parameters, the description is too sparse. It does not explain return value, error conditions, side effects, or prerequisites. Even though the operation seems simple, the agent lacks critical context for successful 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?

The schema provides zero description coverage, and the tool description does not explicitly map project_id and workspace_id to their roles. However, the description's wording 'Move a personal project into a workspace' combined with the parameter names makes the semantics inferable. The description adds some meaning but does not fully compensate for the lack of 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 (move) and the exact resource transition (a personal project into a workspace). It distinguishes itself from sibling tools like 'remove_project_from_workspace' by specifying the direction of the move, and from 'move_document' by targeting projects rather than documents.

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 no explicit guidance on when to use this tool versus alternatives, such as 'remove_project_from_workspace' or direct workspace assignment. It provides no prerequisites, no mention of whether the project must currently be outside any workspace, and no information about fallback or exceptional 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the core behavior (snapshotting the draft into the published version), the effect (public URL access), and the return value (document with public URL). However, it does not mention whether this overwrites an existing published version, any permissions required, or potential side effects, leaving some behavioral traits undisclosed.

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

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

The description is two sentences long, front-loaded with the verb 'Publish', and each sentence adds meaningful information: the action/effect and the return value. There is no redundant or unnecessary wording.

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 simplicity (one required parameter, no output schema), the description adequately covers the action, mechanism, and return value. It does not explain error conditions or prerequisites, but these are not critical for a straightforward publish operation in 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?

The schema describes the only parameter (id) as 'Document UUID' with 100% coverage, so the baseline is 3. The description does not add any parameter-specific details beyond what the schema already provides, though it implies the id is the document to publish.

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 ('Publish') and resource ('uselink document'), and further explains the mechanism ('Snapshots the current draft into the published version') and the result ('makes it accessible via the public URL'). This clearly distinguishes it from sibling tools like unpublish_document and publish_with_assets.

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 the tool is used to publish a document when a draft is ready, but it does not explicitly state when to use this tool over alternatives such as uselink_publish_with_assets or uselink_unpublish_document. No exclusions or alternative recommendations are provided, so the usage context is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden and does an excellent job. It discloses the full side-effect chain: creates a draft, uploads local images, rewrites HTML to CDN URLs, saves the rewritten version, and publishes. It also states the return value (public URL plus assets and rewrites), giving a complete picture of the operation's 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 a single, well-structured paragraph that front-loads the key concept ('One-shot publish') and then lists the steps and return value in a logical sequence. Every sentence provides useful information without redundancy or 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 complex multi-step operation with no output schema, the description adequately covers the return value and the core workflow. It does not mention error conditions or prerequisites, but the combination of clear steps and usage guidance makes it sufficient for an agent to understand the tool's scope and side effects.

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 already describes all three parameters with 100% coverage, so the baseline is 3. The description adds valuable meaning by explaining how 'html' with relative paths triggers asset upload and rewriting, and how 'assets_dir' resolves those paths. This goes beyond the schema's individual descriptions by connecting the parameters to the overall workflow.

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+resource: 'One-shot publish' and enumerates the exact sequence of actions (create draft, upload assets, rewrite HTML, save, publish). This clearly distinguishes it from sibling tools like uselink_create_document, uselink_upload_asset, and uselink_publish_document by combining these steps.

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 usage context: 'Use this when you have an HTML document with relative image paths and want to publish it to uselink in a single step.' While it gives a clear 'when to use', it does not explicitly mention alternatives or exclusion cases, but the 'single step' implies it replaces a multi-step workflow.

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

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

No annotations are provided, so the description carries the full burden. It reveals the return fields and the id/slug exclusivity constraint, but does not disclose error behavior, permissions, or response structure. For a read-only operation, this is adequate but not rich.

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 single sentence that front-loads the primary action, states the key constraint, and lists return fields without redundancy. Every clause adds value, making it concise and well-structured.

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 is simple (2 params, no output schema, no annotations), and the description covers the main behavior, return values, and the id/slug constraint. It lacks error-handling details, but for a straightforward read operation, it is sufficiently complete.

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

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

The input schema already covers both parameters, but the description adds crucial semantics by stating that 'exactly one is required,' which is not encoded in the schema. This clarifies the OR relationship and prevents misuse.

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 reads full document content with a specific verb ('Read'), resource ('uselink document'), and identification method (id or slug). It distinguishes from siblings like uselink_list_documents or uselink_read_project by emphasizing the single-document, full-content scope.

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 specifies the usage condition: read a single document by id or slug, with exactly one required. This gives clear context, though it does not name alternative tools or exclusion criteria, leaving some differentiation to the sibling list.

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

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

No annotations are provided, so the description bears the full burden. It discloses the core behavior (reads a folder and includes counts), but does not mention error handling, permissions, or the full response structure. For a read-only operation, this is adequate but not comprehensive.

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 single, concise sentence that front-loads the primary action and resource. Every word earns its place, with no redundant or vague phrasing.

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 tool with one parameter, no output schema, and no annotations, the description covers the essential context: what it does (reads a folder) and a notable aspect of the result (counts). It could be more exhaustive about other returned fields or error behavior, but it is sufficient for basic use.

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 lists one parameter 'id' with no description (0% coverage). The description adds semantic meaning by clarifying that the id refers to the folder id ('Read a single folder by id'), which is essential for correct invocation. This goes beyond the schema's type/format 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?

The description clearly states the tool's function: 'Read a single folder by id, including doc / live / draft counts.' It uses a specific verb ('read'), specifies the resource ('folder'), and distinguishes itself from sibling tools like uselink_list_folders by emphasizing 'single' and detailing the counts.

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 context for use is implied: this tool is for reading one folder when you have its id. However, there is no explicit guidance on when to use this versus alternatives like list_folders or read_document, nor any mention of exclusions or prerequisites.

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

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

No annotations are present, so the description carries the full burden. The verb 'read' implies a safe, non-mutating operation, but the description does not disclose permissions, error behavior, return format, or any other behavioral traits beyond the basic 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?

The description is a single, front-loaded sentence with no unnecessary words. It conveys the essential purpose clearly and 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?

For a simple by-id read operation, the description is adequate. It could benefit from mentioning the return value or behavior when the project is not found, but given the tool's simplicity and lack of output schema, the current description is mostly complete.

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

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

The description restates the 'id' parameter without adding meaning beyond the schema. It does not explicitly clarify that the ID is the project identifier or provide any additional context about the parameter beyond its type and format 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 clearly states the tool reads a single project by ID, specifying the verb 'read' and the resource 'project'. This distinguishes it from list_projects and other project operations like create or update.

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

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

No guidance is provided about when to use this tool versus alternatives like list_projects or search_documents. The intended use is only implicit from the name and description, with no exclusions or alternative recommendations.

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

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

With no annotations provided, the description carries full responsibility for disclosing side effects. It states the primary effect but omits important behavioral details: whether the operation is reversible, what happens to workspace-specific permissions or shared links, and any authorization requirements. For a mutation tool, this is a notable 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 description is a single sentence that is front-loaded with the action and outcome. No unnecessary words or redundancy. 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?

This is a simple tool with one parameter and no output schema. The description explains the main effect and destination but lacks context about consequences (e.g., whether shared links break, if workspace-specific metadata is lost). It's adequate for the basic operation but misses potential side effects that an agent might need to anticipate.

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 has zero description coverage, so the description must compensate. However, it never mentions project_id or explains that it identifies the project to remove. While the parameter name is self-explanatory, the description adds no explicit semantic link between the operation and the parameter, making it less helpful than it could be.

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 'Remove a project from its workspace' and the outcome 'return it to the user's personal projects'. This specific verb+resource combination distinguishes it from related tools like uselink_move_project_to_workspace, which presumably moves a project into a workspace.

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: use this when you need to remove a project from a workspace and send it to personal projects. It doesn't explicitly name alternatives, but the sibling tool uselink_move_project_to_workspace implies the opposite scenario. No exclusions are mentioned, so it's clear enough for straightforward 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?

With no annotations, the description carries the full burden. It discloses one key behavioral trait: the old slug stops resolving immediately. However, it does not mention permissions, reversibility, validation (e.g., slug uniqueness), or other side effects. Partial transparency but not comprehensive.

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, front-loaded with the main action. Every word earns its place, with 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?

The description gives a clear purpose and one behavioral note, but lacks usage guidelines, parameter details, and error/response information. For a mutation tool with no annotations or output schema, it is insufficient for an agent to fully understand implications and prerequisites.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explicitly explain the parameters. The action implies 'id' refers to the project and 'new_slug' is the desired slug, but no format constraints, examples, or additional semantics are provided.

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 'Rename a project's URL slug' with a specific resource. It also notes a consequence ('old slug stops resolving immediately'), which adds context and distinguishes it from sibling tools like set_url_handle or check_project_slug.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention checking slug availability first, prerequisites, or scenarios where this tool is appropriate or not. The description only states what it does and a consequence.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the nesting behavior but does not disclose that this is a write/mutation operation (though implied by 'post'), nor any effects on the document, permissions required, reversibility, or return value. This is a significant gap for a write tool with no annotation support.

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 single concise sentence, front-loaded with the action ('Post a reply'), and every phrase adds value. 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?

The tool has 3 required parameters, no annotations, no output schema, and the description is minimal. It explains the intent but lacks essential context for a write operation: no return value, no error conditions, no permissions, no follow-up behavior. For a tool of this complexity, the description is under-specified (compare with the update_drive example).

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%, with body and parent_comment_id well-described in the schema, but document_id lacks semantic description beyond format. The tool description does not add extra meaning to any parameter; it only says 'on a uselink document' which loosely maps to document_id. Overall, the schema does most of the work, so a baseline score 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 clearly states a specific action ('Post a reply') and the resource ('existing comment thread on a uselink document'), with additional structural detail ('Replies are nested under the parent comment'). This unambiguously distinguishes it from sibling tools like uselink_resolve_comment or uselink_list_comments.

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: use this tool to reply to an existing comment thread. It does not explicitly name alternatives or exclusions, but the contextual cue 'existing comment' implies prerequisites (the comment must exist), and the verb 'reply' differentiates it from resolve/list tools. Lacks explicit 'when not to use' guidance, so not a 5.

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

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

With no annotations provided, the description carries the full burden. It only states the core state change (mark as resolved) without disclosing reversibility, permissions, or response behavior. For a mutation tool, this is a significant lack of context.

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

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

A single concise sentence that directly communicates the operation with no unnecessary words, making it fully 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?

The description is sufficient for a simple tool with one param and no output schema, but it lacks any note on side effects or return values. Given the simplicity, it's adequate but not comprehensive.

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 already describes the single comment_id parameter with 100% coverage. The description adds no additional meaning to the parameter, so the baseline score 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 clearly states the action with a specific verb 'mark' and resource 'comment thread', explicitly indicating resolution. It distinguishes from sibling tools like uselink_reply_comment by focusing on resolution.

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 usage is implied from the description—use it to resolve a comment thread—but there is no explicit guidance on when to use it versus alternatives like replying or listing comments. No exclusions or alternative tools are mentioned.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It reveals that the tool is bound to the active PAT and that it's a thin wrapper, which implies it inherits the read-only behavior of list_documents. However, it does not explicitly state safety (read-only, non-destructive), pagination behavior, or how search matching works.

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, front-loads the primary purpose, and uses the second sentence to concisely explain the relationship to a sibling tool. Every word earns its place with no 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?

The tool is simple (3 flat params, no output schema), but the description leaves gaps: it doesn't describe return results (beyond implying documents), doesn't explain limit/offset semantics, and doesn't state the safety profile. Given the lack of output schema, more detail about return values would make it more complete.

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

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

The input schema covers only the 'query' parameter with a description, leaving 'limit' and 'offset' undocumented (33% coverage). The description clarifies that 'query' is the free-text search field but adds no meaning for limit or offset, such as their role in pagination. Since schema coverage is low, the description should have compensated but did not.

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 performs free-text search across documents in the active PAT-bound workspace, using a specific verb and resource. It also distinguishes itself from siblings by explicitly noting it's a thin wrapper over uselink_list_documents with the search field set.

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 by referencing uselink_list_documents as the base functionality, implying this tool is for searching while list_documents is for unfiltered listing. However, it does not explicitly state when NOT to use this tool or mention other alternatives like uselink_read_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?

No annotations are provided, so the description carries full burden. It discloses a key behavioral side effect (new documents land here), but omits details such as whether the previous default is replaced, permission requirements, or reversibility. This is adequate but not comprehensive.

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

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

Two short sentences. The first states the action, the second provides the key consequence. No wasted words, 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 simple mutation with one parameter and no output schema, the description gives the basic purpose and side effect. It lacks details about prerequisites (e.g., project existence, permissions) and behavior on repeated calls, but is minimally viable for a setter.

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 has a single 'id' (UUID) with no description, and parameter coverage is 0%. The description refers to 'this' project, implying the id identifies the project to set, but it doesn't explicitly map 'id' to the project parameter. It adds some meaning but relies on inference.

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 this the user's default project') and explains the consequence (new documents without explicit project land here), distinguishing it from sibling project tools. The verb 'Make' and resource 'default project' are 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?

The context is clear: use this tool to set the user's default project. The description doesn't mention alternatives, but none are explicit among siblings, and the purpose is self-evident. 'When no explicit project is given' clarifies the behavioral context for document creation.

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

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

With no annotations, the description carries the full burden. It discloses the timing requirement, input format constraints, and return value ('Returns the updated user'). However, it doesn't explicitly state whether the handle can be changed after being set, which could be a relevant behavioral detail, but the core behavior is well 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?

Three sentences, all information-bearing: purpose, when to use, format, and return value. No redundancy or filler. Front-loaded with the primary action.

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

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

For a simple one-parameter tool with no annotations or output schema, the description provides everything an agent needs: the action, the trigger condition, format validation details, and the return value. It is complete for the tool's complexity.

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

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

Schema description coverage is 100% for the single parameter, including format details. The description restates the format but adds no new parameter-specific semantics beyond the schema, so the baseline score 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 clearly states 'Set the user's public URL handle' with a specific verb and resource. It distinguishes itself from sibling tools by focusing on the user handle, and the additional context about being required before first publish and the USERNAME_REQUIRED error makes its purpose 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 says 'Required once before publishing the first document' and 'Call this when publish returns USERNAME_REQUIRED', giving clear when-to-use guidance. Although it doesn't mention alternatives, no sibling tool performs this exact function, so the instruction 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only states the action without mentioning side effects, required permissions, or reversibility. For a mutation tool, this lack of detail is a significant transparency 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 description is a single, simple sentence with no redundant information. It is front-loaded and easy to parse, though minimal. It earns a high score for conciseness, but not a perfect 5 because it lacks useful elaboration.

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 core action is stated, but there is no mention of return values, effects on associated resources, or prerequisites. Given no output schema and no annotations, the description is not complete enough for an AI agent to fully understand the tool's behavior and implications.

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 a single required 'id' parameter (UUID), but the description does not mention it or explain what it identifies. With 0% schema_description_coverage, the description should compensate for the missing parameter semantics but completely fails to do so.

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 ('Restore') and resource ('previously archived project'), clearly indicating its function as the inverse of uselink_archive_project among siblings. It is unambiguous and distinguishes the tool from other project actions.

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 usage context (restoring an archived project) but does not explicitly state when to use it versus alternatives or provide exclusions. There is no mention of the prerequisite that the project must be archived, nor any reference to the sibling tool uselink_archive_project.

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

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

No annotations are provided, so the description carries full burden. It discloses the key effect (removing public access) and that the draft is preserved, but omits permissions, idempotency, or side effects on comments/assets.

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?

One concise sentence efficiently conveys the purpose and the draft-preservation behavior 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 one-parameter unpublish operation, the description covers what the tool does and the draft preservation. Given no output schema and simple complexity, it is reasonably complete, though it omits any side effects or error conditions.

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 covers the single 'id' parameter 100% with description 'Document UUID'. The tool description adds no additional parameter semantics, 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?

Clearly states the action (unpublish) and resource (uselink document), with scope (removing public access) and distinguishes from siblings like publish_document and delete_document.

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?

Implies usage for unpublishing a document while preserving the draft, but does not explicitly contrast with delete_document or state when not to use. Sibling presence suggests alternatives but no direct mention.

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

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

With no annotations provided, the description carries the full burden. It discloses the draft-only nature and partial update behavior, which is useful. However, it omits details about permissions, reversibility, error handling, or interactions between fields (e.g., format/content coupling), leaving room for more transparency.

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 long, front-loads the action and resource, and every sentence adds value: the first states the operation and fields, the second explains the partial update and draft/publish distinction. No fluff 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?

The description covers the essential workflow of editing a draft and publishing separately, which is the core context. However, it does not mention response format, error conditions, or field-specific behavior beyond partial updates. Given the lack of annotations and output schema, additional detail would be beneficial for a fully self-contained description.

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% (id alone has a description). The tool description names title, content, and format, and clarifies that only provided fields change, adding meaning beyond the schema. But it lacks detailed semantics for each parameter, such as constraints on format when content is provided, so it only partially compensates for the low 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 clearly states the verb 'Update' and the resource 'existing uselink document', and lists the specific fields (title, content, format). It also distinguishes itself from the optional publish step by noting this only updates the draft, which differentiates it from sibling tools like publish and create.

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 explains the draft/publish workflow and directs users to call uselink_publish_document to make changes public, providing a clear alternative. It also states 'Only provided fields are changed', guiding partial update usage. However, it doesn't explicitly mention when not to use this tool for other siblings, though the publish alternative covers the most important distinction.

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

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

With no annotations provided, the description carries the burden of disclosure. It discloses a key behavioral trait: 'Only provided fields change' indicates a partial update semantic, which is valuable and goes beyond the schema. However, it omits other context like permissions, error handling, or return behavior, leaving significant gaps.

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 single concise sentence that front-loads the core purpose and adds a meaningful nuance about partial updates. There is no redundant information or wasted 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?

The tool is relatively simple, but the description is minimal. It lacks details about return values, prerequisites, or error scenarios, and there is no output schema to fill those gaps. The partial-update behavior adds some completeness, making it minimally viable, but more context would be expected for a mutation tool with no annotations.

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

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

Schema description coverage is 0%, so the description must compensate. It lists the parameter names (name, slug, color) but does not explain their meaning, format, or constraints. For example, 'slug' is ambiguous without clarification of URL slug conventions, and 'color' format is unspecified. This is insufficient for a 4-parameter tool with no 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 verb 'Update' and the resource 'folder', and lists the specific fields (name, slug, color) that can be modified. This distinguishes it from sibling tools like uselink_update_document or uselink_update_project, which target different resources.

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 the tool (when updating folder metadata) and clarifies that only provided fields are changed, giving a usage hint. However, it does not explicitly mention alternatives, exclusions, or when not to use it (e.g., to move a folder use uselink_move_folder).

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 adds a key behavioral detail ('Only provided fields change') beyond the schema, indicating partial update semantics. However, with no annotations, it does not disclose other behavioral aspects like permissions, idempotency, or return values, leaving the description to only partially carry the transparency burden.

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 fluff, front-loaded with the action and resource. Every word earns its place, making it highly concise and well-structured.

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 update tool with only 3 parameters and no output schema, the description covers the essential behavior including partial update. It lacks guidance on tool selection and does not describe return values, but given the low complexity, it is fairly complete with only minor gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'name' and 'slug' as updatable fields but provides no additional meaning for the 'id' parameter or constraints on slug format/uniqueness, leaving parameter semantics under-documented.

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 ('Update') and resource ('a project'), and specifies the scope ('name and/or slug'). This distinguishes it from sibling tools like uselink_update_document and uselink_rename_project_slug.

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 no guidance on when to use this tool versus alternatives such as uselink_rename_project_slug or uselink_update_document. It only states what the tool does, leaving usage context implicit.

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

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

With no annotations, the description carries the full burden. It discloses the return value (asset with CDN URL) and the attaching behavior, which is useful. However, it does not mention side effects like overwriting, permissions, error conditions, or document state requirements, leaving gaps in transparency for a write operation.

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 short sentences, front-loaded with the core action, and every sentence earns its place: upload action, return value, and how to use the result. 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 simple tool with 2 parameters, no output schema, and no annotations, the description adequately covers the purpose, the input expectations, and the return value usage. It does not explicitly compare with upload_zip, which could help in selecting the right tool, but overall it is complete enough for an agent to invoke 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 the baseline is 3. The description adds minimal extra meaning beyond the schema—'local filesystem' reinforces file_path, but the schema already specifies 'path to file on disk' and 'Document UUID'. No additional syntax or format details are provided, so it stays at baseline.

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

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

The description clearly states the action ('Upload'), the resource ('a single image or file'), and the target ('attach it to a uselink document'). It distinguishes itself from sibling tools like uselink_upload_zip by specifying 'single' and from list tools by the attachment and return value.

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: use this when you need to attach a single file to a document and then use the returned URL in HTML/Markdown. It does not explicitly exclude alternatives or mention when to use upload_zip instead, but the scope is clear enough for an agent to infer the primary use case.

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

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

With no annotations provided, the description carries the full burden of behavior disclosure. It transparently explains the extraction, storage, rewriting of <img src> to CDN URLs, and the return of rewritten HTML plus asset lists. This goes beyond a basic 'uploads a zip' and discloses key processing steps, though it omits potential edge cases like invalid zips or authentication requirements.

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 no fluff. The first sentence states the core action, and the second details the outcome. Every word earns its place, making it highly concise and well-structured.

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?

Despite having no output schema, the description explicitly states the return value (rewritten HTML plus created/skipped assets), which compensates for that lack. The tool's complexity is adequately covered, including the extraction and URL rewriting behavior. The description is sufficient for an agent 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 coverage is 100%, with both parameters (zip_path and document_id) already well-described in the schema. The description adds context about the zip containing HTML and assets, but this does not materially enhance the parameter semantics beyond what the schema provides, so the baseline score 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 clearly specifies the verb 'Upload' and the resource 'a zip archive containing an HTML page and its referenced assets,' distinguishing it from sibling tools like uselink_upload_asset (single asset) and uselink_publish_with_assets (publishing). It also details the server-side processing, making the tool's purpose unmistakable.

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 for when to use this tool: when you have a zip archive that contains an HTML page and its assets. It doesn't explicitly state 'use this instead of uselink_upload_asset' or mention exclusions, but the use case is implicit enough for an agent to infer the appropriate scenario.

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