Anima MCP Server

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

The description goes well beyond the annotations, disclosing asynchronous behavior for generation types, immediate returns for own-code types, the inclusion of a read-write git token in the response, and the distinction between live app URLs versus markdown/asset artifacts. It even explains that a generated markdown import returns documentPreview fields. No annotation contradiction exists.

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

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

The description is long, but the complexity justifies it. It is front-loaded with the most critical facts—never edits existing, do-not-use list, and the async warning—and organized with clear headers like 'type:' and 'Returns:'. There is minor redundancy around return handling, but overall it is structured well enough for an agent to extract actionable guidance without reading linearly.

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

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

With no output schema, the description fully documents return values for both generation and own-code paths, including sessionId, previewUrl, gitRemoteUrl, revision, nextSteps, and fileCount. It also covers the polling workflow, the condition for calling artifact-get_git_token, and the URL behavior per artifactType, making the tool safe to invoke correctly in almost any situation.

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

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

Although schema coverage is 100%, the description adds substantial cross-parameter meaning: it clarifies the easy-to-confuse type versus artifactType axes, per-type required fields, files/zipUploadId mutual exclusivity, workspaceId requirement conditions, and that name is ignored for p2c/l2c/f2c. This goes far beyond the schema's per-field 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 opens with a precise statement: 'Create a NEW artifact in Agent Grid; never edits an existing one.' It clearly specifies the verb, resource, and scope, and differentiates itself from artifact-edit, artifact-update_metadata, and artifact-publish by explicitly naming what it is not for.

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

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

Usage guidance is exceptionally explicit: it names exact alternative tools for editing, metadata changes, and publishing, and instructs agents to poll artifact-status with { sessionId, wait: true } before replying. It also warns against calling artifact-create multiple times for the same generation request, removing ambiguity about when to use this tool versus siblings.

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

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

Annotations already indicate a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds substantial context: it never edits existing artifacts, returns a ready artifact, lists the exact return fields, and instructs sharing the artifactUrl with the human. This goes well beyond the annotations and sets clear expectations.

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

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

The description is compact yet information-dense: purpose is front-loaded, followed by call constraints, return values, and sibling routing. Every sentence earns its place, and nothing is redundant with the schema or annotations.

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

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

For a create tool with two optional parameters and no output schema, the description covers the purpose, invocation, parameter constraints, return structure, and recommended next steps (explore, edit, publish). An agent can call it correctly and know what to do with the result without any further lookups.

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

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

Schema coverage is 100%, so the schema fully documents both 'name' and 'workspaceId' with defaults and source guidance. The description reiterates defaults and adds a useful constraint ('No files, ZIP upload, framework, or artifact type are accepted'), but overall it adds only marginal value beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Create a NEW knowledge artifact from Anima's knowledge-base template') and explicitly distinguishes it from editing ('never edits an existing one') and from other creation modes ('No files, ZIP upload, framework, or artifact type are accepted'). This differentiates it clearly from artifact-create, artifact-edit, and other siblings.

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

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

It specifies how to call the tool ('Call with no arguments, or with an optional name... and workspaceId'), states what is not accepted, and routes the agent to sibling tools for subsequent actions ('Use artifact-explore and artifact-edit to inspect and change its contents. Only use artifact-publish when the user explicitly asks for a public deployment'). The 'never edits an existing one' line implicitly warns against using it for edits, giving a when-not.

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 goes beyond the annotations by disclosing soft-delete semantics: content/assets/database content are retained, MCP cannot permanently delete, write access is required, and repeated deletion succeeds. This meaningfully expands on the structured hints without contradicting them.

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

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

The description is front-loaded with the core purpose alerting the agent to required user intent, then proceeds through prerequisites, behavior, and return shape. Every sentence adds operational value; there is no filler or repetition of the name/title.

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

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

For a mutating tool with no output schema and one required parameter, the description supplies the essential invocation context: explicit request requirement, unpublish workflow, publish-in-progress handling, soft-delete behavior, idempotence, and return shape. An agent has enough information to call this tool safely and 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?

The single parameter sessionId is already fully described in the JSON schema as the session ID of the artifact to delete. The description restates this mapping ('Set sessionId to the ID of the artifact to delete') but does not add meaningful new semantics beyond what the schema already provides. With 100% schema coverage, 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 opens with a specific verb and resource: 'Delete an EXISTING artifact.' It then distinguishes this tool from deletion inferred by cleanup requests and sets an explicit boundary ('Use this tool only when the user explicitly asks to delete that artifact'). This clearly separates it from siblings like artifact-unpublish.

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

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

Provides explicit when-to-use and when-not-to-use guidance, and practical sequencing: verify explicit user intent, do not infer deletion from cleanup, unpublish before deleting, wait for in-progress publishes, and note that authorized repeated deletions succeed. This is strong operational guidance.

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

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

Beyond annotations, it discloses non-idempotency, retry behavior (list artifacts before retrying), atomic failure when a database cannot be copied, and what is not copied (chat, custom domains). This is substantial behavioral context that annotations alone could not convey.

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

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

The description is longer than average but every sentence carries operational information, and it is front-loaded with the primary purpose before requirements and return shape. It could be tightened slightly, but the structure (purpose, exclusions, requirements, retry safety, returns) is logical.

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

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

With no output schema, the description compensates by enumerating the exact return fields and their conditional presence (playgroundUrl/previewUrl). It covers failure semantics, permissions, retry behavior, and destination selection—enough for an agent to invoke it correctly without external 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 parameter descriptions already cover all three parameters (100% coverage), so the baseline is 3. The description adds real value by specifying the default name ('<source name> (Copy)') and clarifying when workspaceId is optional vs required—information absent from 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 plus resource: 'Duplicate (clone) an EXISTING artifact into a new, independent artifact.' It states the key scope (copies code, assets, supported database content; does not copy chat/custom domains) and clearly separates this from artifact-create/delete/edit by emphasizing it acts on an existing artifact.

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

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

It gives concrete conditions for use: source must be readable and in the caller's current team, caller needs write access to the destination workspace, and it explicitly contrasts itself with local git clone. It does not explicitly name a sibling like artifact-create as the alternative for creating from scratch, so it stops just short of an explicit when-to-use vs alternative routing.

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

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

Annotations already state destructiveHint=true and readOnlyHint=false, but the description adds substantial behavior: operations are committed atomically as ONE commit, REVISION_CONFLICT occurs on staleness, the artifact URL remains unchanged, drafts are never edited/promoted/discarded, and move does not rewrite imports. It also notes the live preview updates immediately. This goes well beyond the annotations without contradicting them.

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

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

The description is long but dense; every sentence addresses a distinct failure mode or usage rule (atomicity, draft handling, baseRevision conflicts, op choice, move caveat, alternatives). It front-loads the core function and scoping before diving into conditions, and there is no filler or repetition.

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

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

For a complex mutation tool, the description covers inputs, ordering, atomicity, conflict handling, draft behavior, and alternatives remarkably well. The only gap is that there is no output schema and the description does not state what the successful response contains (e.g., new commit id), leaving the agent to guess the return shape. Otherwise 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 100%, so the schema already documents all parameters thoroughly. The description nevertheless adds valuable operational guidance: prefer str_replace for existing files, send exact snippets, and be aware that move does not fix import paths. This is complementary but largely reinforces rather than replacing the schema's already-rich parameter documentation.

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

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

The description uses a specific verb-resource pair ('Change the files of an EXISTING artifact and commit them') and immediately scopes itself by stating it never creates a new artifact. It also names sibling tools like artifact-update_metadata and artifact-get_git_token to route away from non-file-edit operations, making it easy to distinguish from the many artifact siblings.

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

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

The description explicitly says when to use this tool (editing existing artifact files without git/shell) and when not to (renaming/visibility changes → artifact-update_metadata; huge repos/full git workflows → artifact-get_git_token). It also gives a critical precondition: read files first with artifact-explore and pass the returned revision as baseRevision, plus the Canvas draft condition for acknowledgeCanvasDraftRevision. This is fully explicit 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?

Despite annotations already declaring readOnlyHint and non-destructive, the description adds substantial behavioral context: draft requires write permission, assets are detected by byte-check (SVG reads as text), empty searches explain notSearched.excluded and notSearched.assets, unwritable paths are mapped in tree, and response includes deferred files and truncated text with size budget. No contradiction with annotations; rich operational 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 dense and every sentence carries unique operational information—no filler or repetition. However, it is a single long unbroken paragraph, which makes scanning harder for an agent needing quick reference; slightly more structure (e.g., separating actions, revision, assets) would earn a 5.

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 12 parameters, no output schema, and rich edge cases, the description covers return semantics (revision, asset, notSearched, unwritable, deferred, truncated, nextCursor), version undo, asset distinction, search boundary behavior, and pagination. It even addresses the empty-search diagnostic path. Nothing essential for correct tool use is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning well beyond the schema: 'path' is explicitly NOT a glob, 'search' matching never spans lines, 'range' is only valid for a single file, 'revision' is not a branch/tag/range and commits are on main only, 'paths' for read is required and up to 10 files, and each action's expected parameter usage is spelled out (e.g. 'Omit paths to list changed paths'). This materially improves correct invocation.

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

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

Opens with a precise verb+resource statement: 'Inspect the files of an EXISTING artifact: list them, search their text, read them, or review the commit history.' This clearly distinguishes the inspect/read role from sibling tools like artifact-edit (modify) and artifact-status (build progress), leaving no ambiguity about 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?

Explicitly states when to prefer this tool: 'Works with no shell, no git and no network access, so prefer it whenever you cannot run git.' It also names an alternative for a different use case: 'For generation or build progress use artifact-status instead.' The description even prescribes a typical workflow (search → read → artifact-edit) and explains when to use a revision for undo, giving agent clear selection and invocation 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?

The description goes far beyond the annotations. It discloses the multi-step flow, the exact S3 upload requirements (order of form fields, file last, no size/Content-Length field), the 204 success response, one-file-per-id, single-use, 30-minute expiry, 32 MB max, automatic Git LFS behavior for files over 10 MB, and the security note about uploadFields being a secret. This is exceptionally transparent about behavior and constraints.

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

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

The description is dense but well-structured with clear sections (Flow, Rules, Returns). It front-loads the core purpose and the 256 KB threshold. It is longer than typical, but every sentence carries operational information an agent needs. The only minor issue is that the length could be slightly trimmed, but the structure keeps it navigable.

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

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

For a tool with no output schema, the description fully compensates by listing the return fields (success, assetUploadId, uploadUrl, uploadFields, expiresAt, maxBytes, nextSteps). It also covers the complete workflow, error-prone details (S3 field order), constraints, and fallback paths. An agent has everything needed to invoke this tool and execute the subsequent upload 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 schema already documents both parameters. The description adds meaningful context: it explains that only the filename's extension is read for typing the upload, and that the actual path is passed later to artifact-edit. It also clarifies sessionId's format and source. This adds value beyond the schema, though the schema already covers the basics.

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 purpose: 'Step 1 of adding a LARGE asset to an EXISTING artifact' and distinguishes it from the alternative artifact-edit for smaller files. It names the specific verb (stage/get upload URL) and resource (artifact asset), and the flow makes the tool's role unambiguous.

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

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

The description provides explicit when-to-use guidance: use for files over 256 KB, and explicitly says smaller files should go to artifact-edit directly. It also names alternatives (artifact-edit with base64, artifact-get_git_token) and gives a fallback for hosts that cannot make HTTP requests. This is comprehensive routing guidance.

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

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

The description adds substantial behavioral context beyond the readOnlyHint/destructiveHint annotations. It explains the returned gitRemoteUrl contains a short-lived token scoped to one artifact, that tokens cannot be renewed, how to recover from expiry, that pushing updates the live artifact, and to treat the URL as a secret. It also clarifies that the tool itself is read-only even though the returned credentials may allow writes, which is consistent with the annotations.

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

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

The description is long but every sentence earns its place. It front-loads the purpose and when-to-use, then covers return values, usage steps, error handling, security, and alternative tools. There is no fluff; each clause adds necessary operational detail. The structure is logical and efficient for the complexity of the tool.

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

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

For a tool with no output schema, the description fully explains what is returned (gitRemoteUrl and commitAuthor), how to use it after cloning, and how to handle failures (token expiry vs. DNS errors). It also points to artifact-update_metadata for rename/visibility tasks, covering all relevant operational scenarios. An agent can invoke this tool correctly with no ambiguity.

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% for both parameters, so the schema already documents sessionId and ttlSeconds in detail. The description adds some context (e.g., the example URL format and the relationship between ttlSeconds and the renewal workflow), but that information is largely present in the schema itself (e.g., 'Expired tokens cannot be renewed — mint a new one and update the git remote'). Thus the description adds marginal value beyond the schema, warranting the baseline of 3.

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

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

The description opens with a clear verb-resource-purpose statement: 'Get git access to an EXISTING artifact, for local development with a real git client.' It also explicitly names sibling alternatives (artifact-explore, artifact-edit) and explains when each is preferred, so the agent can distinguish this tool from the rest of the list.

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

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

The description gives explicit conditions for use: 'Use this when you HAVE a working shell with git and outbound network access AND the job suits a local checkout...' and lists concrete cases (large refactor, running/testing, branches, history rewriting). It also states when NOT to use it ('For ordinary reading and editing... prefer artifact-explore and artifact-edit') and how to handle DNS/proxy failures by falling back to artifact-edit. This is exemplary guidance.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses that uploadUrl is a secret, the 50MB zip limit, that shell/executable files are skipped and reported, that zipUploadId is single-use, and the 30-minute expiry window. This adds significant behavioral context without contradicting any annotation.

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

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

The description is well-structured with clear sections (Flow, Rules, Returns) and every sentence provides necessary information. It is detailed but not verbose, with no wasted words, making it easy to scan and understand.

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

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

For a tool that is part of a multi-step import process, the description covers the entire flow, constraints, secrets, and return values. Even without an output schema, it lists exactly what the tool returns, making it fully self-contained for correct usage.

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 enriches the single parameter 'purpose' far beyond the schema's enum. It explains when to omit it, what passing 'asset' means, and the exclusivity rules (asset artifacts can only be created from reserved uploads). This adds essential meaning that the schema alone lacks.

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 specific purpose: it is step 1 of the zip import flow for artifact-create, used for imports with binaries or large source. It distinguishes from inline file passing and implicitly from the asset upload sibling by explaining the purpose parameter, making its role 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?

It explicitly states when to use this tool (for binaries or over ~100 KB of source) versus the alternative (inline for small text-only projects). It also outlines the full multi-step flow, including the required sequence and the use of artifact-create afterwards, giving clear context for selection.

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

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

Annotations (destructiveHint=true, readOnlyHint=false) are consistent with the description, and the description adds rich context beyond them: 'Publishing makes the content PUBLIC to the world,' only git HEAD is deployed ('uncommitted edits are not included'), designSystem mode 'always fails with an enterprise contact link,' and detailed rendering behavior for markdown artifacts. This explains the nature of the destructive action rather than merely flagging it. No annotation contradiction.

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

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

The description is long but well-structured with headers (**What goes live:**, **Modes:**, **Returns:**), and the most decision-critical facts — asset artifacts can't be published, content becomes public, and when NOT to call it — are front-loaded. The markdown rendering details (lexicographic README selection, accTitle/accDescr, content-type of index.md) are more granular than strictly necessary but do serve the agent's follow-up messaging to the user.

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 tool with 4 params, 2 modes, 3 artifact types, no output schema, and a public-exposure consequence, the description is thorough: it covers preconditions, return shape { success, liveUrl, subdomain }, exclusions (asset artifacts, designSystem), the public-visibility warning, and the sharing alternative. An agent has everything needed to decide whether to call it and what to expect in return.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value on top of the schema by clarifying behavioral semantics of the parameters: it explains that 'webapp' is the default and works for both artifact types, that designSystem 'always fails' making packageName/packageVersion effectively unusable, and it specifies sessionId's origin. This goes beyond the schema's per-parameter text.

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

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

States a specific verb and resource — 'Publish an artifact — deploys its committed files (git HEAD...) to a live public URL' — and disambiguates artifact types explicitly: 'Works for app AND markdown artifacts; an asset artifact cannot be published.' This clearly differentiates it from siblings like artifact-create, artifact-unpublish, and artifact-edit without needing to inspect them.

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

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

Gives explicit when-to-call guidance: 'Call this only when the user explicitly asked to publish/deploy; otherwise share that URL and offer publishing as a follow-up question.' It also states what NOT to do, names the alternative action (sharing artifactUrl), and warns that designSystem 'is NOT available over MCP... Do not offer it as a capability.' Prerequisites are covered via 'Requires a sessionId from a previously created artifact (via artifact-create).'

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral context: asynchronous generation, timeout after 45 seconds, and the exact wait semantics. It also discloses the return structure with fields for different statuses, which is beyond the annotations.

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

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

The description is well-structured and front-loaded: purpose first, then usage flow, then parameter specifics, then return details. Every sentence adds value, and it avoids redundancy with the schema. It is detailed but not bloated.

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 fully equips an agent to use the tool correctly: what it does, when to call, how to wait, what the sessionId is, and what the return object contains. For a complex async tool, nothing needed is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters. However, the description adds crucial meaning: it explains that sessionId can derive from artifact-create or from a URL's last segment, and elaborates on the wait behavior (45-second timeout, recommended true, not to spin). This is far beyond the schema's basic definitions.

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

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

States a specific verb ('Check') and resource ('build status of an EXISTING artifact'), explicitly ties it to artifact-create, and clarifies it is read-only. This clearly distinguishes it from sibling tools like artifact-edit or artifact-delete.

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

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

Gives explicit instructions: call right after artifact-create, keep calling until status is no longer 'generating', and warns against tight loops with wait: false. It also explains when to use wait: true vs false, leaving no ambiguity for the agent.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds valuable context: it clarifies that the destructive effect is limited to the live URL, not the artifact itself, and that the subdomain is reused on republish. This goes beyond the annotations and helps the agent understand the exact scope of the destructive action. It doesn't mention rate limits or auth, but for this tool the key behavioral disclosure 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?

The description is well-structured and front-loaded: the core action and effect come first, followed by exclusions, then parameter details and return value. Every sentence earns its place, and the formatting with bold fields and a returns line makes it scannable.

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

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

For a single-parameter tool with a simple output ({ success, message }), the description covers the action, the scope of the destructive effect, the required parameter, how to get it, and the inverse operation. There is no output schema, but the return shape is stated inline. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents sessionId. The description adds extra meaning by explaining how to obtain sessionId (returned by artifact-create, or extracted from the URL's last path segment), which is genuinely useful beyond the schema's one-line description. This is above the baseline 3.

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

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

The description states a specific verb ('Take an EXISTING published artifact offline'), a clear resource (published artifact), and the effect (clears its live URL so the deployed site stops being reachable). It also explicitly names the inverse sibling (artifact-publish), which distinguishes it from other artifact tools.

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 says when to use it (for an existing published artifact) and what it does NOT do (does not delete artifact/code/content). It also names the inverse sibling artifact-publish, giving the agent a clear alternative. It even explains how to derive sessionId from an artifact URL, which is practical usage guidance.

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

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

Annotations already flag non-read-only, open-world, and destructive semantics. The description usefully narrows the side-effect surface to metadata only (never code/content) and names capability requirements, though it does not detail the destructive implications flagged by destructiveHint.

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

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

Front-loaded definition, one-line scope limitation, and compact routing guidance. The field details are brief and the capability notes are grouped without 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?

Includes return shape, capability requirements, sibling distinctions, and the at-least-one-parameter rule. It doesn't enumerate error cases, but for a simple metadata update with full schema coverage and a return description this is reasonably 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 adds meaning beyond the schema: at least one of name/privacy must be sent, both may be set in one call, and sessionId can be derived from the artifact URL. This directly resolves ambiguity not present in the schema.

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

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

Opens with a precise definition: update metadata (name/visibility) on an existing artifact, and explicitly says it is not for code/content. This cleanly separates it from artifact-edit and artifact-publish.

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

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

Gives explicit routing guidance: use artifact-edit for code/content changes, artifact-publish for publishing, and artifact-create for new artifacts. It also says sessionId comes from an existing artifact and how to extract it from a URL.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by explaining it converts designs into files. It also discloses the authentication requirement (X-Figma-Token) and the asset-download behavior, which are behavioral details beyond the schema. It stops short of rate limits or failure modes, but the key side effects and prerequisites are covered.

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

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

Purpose is front-loaded in a single sentence. The description is organized into labeled sections (Authentication, Inputs, Returns, Asset Handling), which makes it easy to scan. It is somewhat longer than strictly necessary, but every section adds distinct value; no filler or repetition of the input schema.

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

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

Even though there is no output schema, the description enumerates the return aspects (generated code files, assets list, usage guidelines) and explains how to handle assets by downloading them from the returned URLs. It also states the auth requirement upfront. For a code-generation tool of this complexity, this is a complete picture an agent needs 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?

The schema descriptions already cover the parameters well (with defaults and examples), giving a baseline of 3. The tool description goes further by teaching the agent how to extract fileKey from a URL and how to convert '-' to ':' for node IDs, plus recommending detection from the user's project to pick framework, styling, and language. This is actionable guidance that materially improves parameter selection.

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

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

The opening line states a specific verb and object ('Convert a Figma design to production-ready code') that precisely captures the tool's function. The description continues with concrete parameter explanations)Skip. Among the sibling tools (artifact-create, design_system-get_manifest, etc.), this one is clearly the Figma-to-code converter, so there is no ambiguity about its unique role.

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 the tool is used (when a Figma design should become code) and gives practical instructions for parameter selection, notably 'Detect from the user's project' for framework, styling, and language. It does not explicitly name alternative tools or state exclusion conditions, but sibling names make the distinction 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavior beyond the schema by stating the return shape ('JSON object mapping file paths to their content'), which is not present in the input schema. It doesn't mention edge cases, but given the read-only nature, this is reasonable.

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 redundancy. The first sentence states the action and outcome; the second gives usage context and examples. Every word earns its place, and the key behavior 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 two-parameter tool with no output schema, the description is sufficient. It specifies the return type, the sequencing relative to the manifest, and gives representative file paths. An agent has everything needed to call it correctly without further clarification.

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 both params, so the baseline is 3. The description adds a small amount beyond the schema by listing example file paths and clarifying the mapping in the return, but it does not deeply enrich parameter meaning. It provides a practical orientation but no new semantic constraints.

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 ('Fetch') and a clear resource ('multiple documentation files by their paths'), and specifies the return format ('JSON object mapping file paths to their content'). It also distinguishes this from the sibling design_system-get_manifest by implying the manifest is for listing while this is for retrieving specific files.

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

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

The description gives explicit usage timing: 'Use this after getting the manifest', and provides concrete examples (README.md, COMPONENTS.md, TROUBLESHOOTING.md). This clearly instructs when to use this tool relative to its sibling and what it is for.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=falsekin. The description adds useful behavioral detail by specifying the return value: a JSON object mapping paths to metadata (description, type, optional tags/category). It doesn't discuss auth or errors, but the safety profile is covered by annotations.

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

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

Two concise sentences. The first front-loads the purpose; the second clarifies the return shape without repetition.

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

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

For a simple readOne operation with a single parameter, the description adequately explains what is returned. It lacks details like error behavior or whether the manifest is cached/large, but the output shape and read-only nature are enough for an agent to decide whether to call it.

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

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

Schema coverage is 100%: the only parameter dsId is described as 'The design system ID'. The description adds nothing beyond the schema about dsId's format or how to find a valid ID, so it stays at the baseline for high coverage.

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

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

The description uses a specific verb ('Get') and names a concrete resource ('manifest.json file'), and explains what it contains (mapping of file/folder paths to metadata). It doesn't explicitly contrast with the sibling design_system-get_files, but the resource is distinct enough.

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 use case – retrieve the manifest describing the design system documentation structure – but offers no explicit guidance on when to choose this over the similar-sounding design_system-get_files sibling.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavior beyond that: unassigned comments are anyone's to take but not reserved, resolving closes the comment for all named parties, isLatest=false means the artifact moved, replies can change the request, and resolveTrailer must be copied to close comments. No contradiction with annotations.

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

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

The description is long and dense, but it is front-loaded with purpose and when-to-call guidance, then organized by anchors, assignment semantics, replies, and resolution. Some content, such as resolveTrailer and reply-versus-resolve guidance, is arguably more relevant to sibling tools, but it helps the agent understand the list output. It earns a high score but loses a point for length and occasional 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?

With no output schema, the description must carry the burden of explaining return values and interpretation, and it does: anchors for both app and document artifacts, shared markup warnings, isLatest behavior, unassigned and alsoAsked semantics, no-anchor comments, status/replies, and resolveTrailer. The tool is complex enough that this depth is needed, and it is present.

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

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

Schema description coverage is 100%: both limit and sessionId have detailed descriptions with defaults, bounds, and an example for sessionId. The description adds some context for sessionId by mentioning 'across every artifact you can reach,' but it does not need to compensate for schema gaps. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Read the change requests humans have addressed to YOU on their artifacts.' It defines what a review is and clearly separates this tool from review-resolve and review-reply by noting those are for closing or replying rather than listing. An agent can tell what this tool is for without needing the title or schema.

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

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

It gives explicit triggers: 'Call this when a human says they left you comments or asked for changes, and at the start of work on an artifact you have been reviewed on before.' It also provides alternatives: 'Use review-resolve when no commit will, and review-reply to say something without closing it.' This is strong when/when-not guidance.

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

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

The description discloses important side effects beyond the annotations: the comment stays open, the reviewer will see the reply on the same thread, responses may be delayed, closed comments stop accepting replies, and mentioning someone emails them. It also clearly states agents cannot be mentioned, which is non-obvious 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 long but dense: the main purpose and sibling distinction are front-loaded, followed by workflow and behavioral caveats. Every sentence contributes useful guidance, though some points are repeated from the input schema and the single-flow structure could be tighter.

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

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

For a tool with no output schema, the description gives agents a complete mental model: how to reply, how to read the reviewer's response, whether to wait, which comments are eligible, and how mentionUserIds changes behavior. It also names the sibling tools explicitly, so context switching is clear.

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 documents all parameters at 100% coverage, including message behavior and mentionUserIds. The description adds practical value on top—such as when to bring in a person, that IDs must come from mentionablePeople, and that each mention triggers an email—but the additional nuance is somewhat redundant with the parameter 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 states a concrete action—reply to one review comment—and immediately adds the key differentiator of leaving the comment open. It also explicitly contrasts with review-resolve, so the agent can distinguish it from the closest sibling.

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

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

The description explicitly says to prefer this tool over review-resolve whenever the exchange is not finished, and explains that resolving closes the thread. It also gives eligibility guidance, such as replying only to comments addressed to you or marked unassigned, and clarifies the mention flow for pulling in humans.

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

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

The annotations indicate idempotentHint=true and readOnlyHint=false, but the description adds meaningful context: it states that closing ends the exchangeaiman, that it is safe to retry (already closed comments return resolved:false), and that it works without a commit. This goes beyond the annotations, providing important operational details about the tool'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 paragraph with multiple sentences, but it is dense and information-rich. It is not overly long for the complexity of the tool, and each sentence adds value: purpose, use cases, alternatives, constraints, and retry behavior. It is well-structured with logical flow from what it does to when to use it to edge cases.

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

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

For a tool with only 2 parameters, no output schema, and annotations covering mutability and idempotency, the description covers the essential aspects: what it does, when to use it, how to use it, and what happens on retry. The only minor gap is not explicitly stating the outcome (that the comment becomes 'resolved'), but the description implies it. Overall, it is quite 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?

The schema description coverage is 100%, meaning the schema already fully documents both parameters. The description adds context for 'note' (what it is for) and 'commentId' (how it is obtained), which is slightly beyond the schema but not significantly. The baseline is 3 given the coverage, and the description doesn't add substantial new meaning 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 the specific action: 'Close ONE review comment WITHOUT a commit' and explains its intended use cases (questions answered, deliberate decisions not to make changes). It distinguishes itself from siblings like review-reply and the commit trailer mechanism, making it easy to know exactly what this 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 provides explicit guidance on when to use this tool versus alternatives: it contrasts with the commit trailer (for when a commit addresses the comment) and review-reply (for asking a question instead of answering). It also notes that closing 'ends the exchange' and specifies that you may close comments addressed to you or marked 'unassigned'. This is comprehensive with clear exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's read-only claim aligns. It adds value by disclosing truncation behavior (truncated: true means more exist) and instructing to never report a total or claim no artifacts exist, which are important behavioral nuances beyond the annotations.

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

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

Two sentences plus a return block, all essential. The core action and scope are front-loaded, and the return structure is clearly delineated. 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?

For a 1-param, optional list tool, the description covers scope, return format, truncation semantics, and reporting guidance. It fully equips an agent to call it correctly without an output schema.

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

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

Schema coverage is 100% with a clear description of workspaceId. The description reinforces that it's optional and specifies the source of the id (from workspace-list_workspaces), adding meaningful context beyond the schema alone.

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

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

States a specific verb (list), resource (artifacts), and scope (accessible ones, optionally filtered by workspaceId). It also distinguishes from siblings by noting sessionId is used by artifact-explore, artifact-edit, and artifact-get_git_token, clarifying this is the listing tool.

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?

Clearly explains when to use it (to list artifacts across all accessible workspaces or a single one) and how to scope with workspaceId, even pointing to workspace-list_workspaces for the id. It does not explicitly contrast with alternatives, but the purpose is unambiguous given the sibling set.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the meaning of an empty list ('you have been granted no workspace, not that the team has none: ask the user for access'), which is a non-obvious operational detail. It also explains the meaning of the `capabilities` field and `isGeneral`. This is above what annotations provide, though it doesn't discuss rate limits or pagination.

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

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

Front-loads the purpose, then details on return shape and semantics in clearly delimited sections. Every sentence adds distinct value (opaque IDs, return fields, empty-list meaning). No filler.

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

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

For a no-param, read-only listing tool with no output schema, the description is complete: it covers purpose, return shape, field meanings, edge-case semantics (empty list), and the relationship to a sibling. An agent has everything needed to invoke and interpret results 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?

Zero parameters, so baseline is 4. The description confirms 'Takes no parameters,' which is consistent with the empty schema.

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

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

States a specific verb ('List') and resource ('workspaces you can access') and adds scope ('what you may do in each'). It also explicitly distinguishes itself from workspace-list_artifacts by explaining the relationship (the artifact row carries the workspace id). No ambiguity about which sibling to pick.

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

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

The description implies when to use it (discovering reachable workspaces and their capabilities) and explains the relationship to workspace-list_artifacts. It doesn't name explicit exclusions or say 'use X instead of Y' when the user already knows the workspace id, but the context is clear.

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

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

Annotations declare destructiveHint, idempotentHint and readOnlyHint=false, but the description adds the crucial meaning: content (repo, sessionId, URL, history, deployment) is preserved while access/listing changes, and moving to the same workspace is a no-op. This clarifies what 'destructive' actually destroys — reachability, not data.

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

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

Well front-loaded (the core action and its non-destructive nature come first), with permissions and returns clearly sectioned. Slightly prose-heavy in the middle paragraph but each sentence carries information.

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

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

For a 2-param mutation with no output schema, the description covers permissions, idempotency semantics, the access-change consequence, and an inline Returns block. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented there, including their source tools. The description largely restates the same facts rather than adding format or edge-case detail beyond the schema.

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

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

States a specific verb (re-file/move) and resource (artifact) with explicit scope: another workspace of the same team. An agent can distinguish this from artifact-duplicate, artifact-edit and the other artifact-* siblings without opening schemas.

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

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

Gives clear context for when to use it and a strong caveat: confirm with a human before moving something they did not request, since access changes. It stops short of naming sibling alternatives (e.g. duplicate vs move) explicitly.

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