mythex

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the mutation/open-world nature is covered. The description adds a useful routing fact ('the website serves /api too') but omits what an agent would want for an open-world DNS operation: whether verification is required, what happens on duplicate hostnames, and whether the call blocks on propagation.

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

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

Two tight sentences with the primary action front-loaded and the conditional parameter guidance second. No filler, nothing repeated from the title.

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

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

For an open-world mutation with no output schema, the description should cover prerequisites and follow-ups (DNS records, verify_domain, primary-domain designation). It covers the service-vs-website distinction well but stops short of the surrounding workflow an agent needs to call this 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 67%, so service and project_id are documented in the schema and the description reinforces service semantics. The required hostname has no schema description and the prose does not specify its expected format (bare hostname vs URL, subdomain rules), leaving the one required parameter under-explained.

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

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

States a specific verb+resource ('Add a custom domain to the published app') and immediately clarifies the two modes of operation (website vs backend service). An agent can distinguish it from list_domains/remove_domain/verify_domain by the write framing, though no sibling is named explicitly.

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

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

Gives conditional guidance on the service parameter ('omit for the website' vs 'pass a backend service name'), which is real usage direction. But it never says when to use this versus set_primary_domain, or whether verify_domain must follow, so the workflow context is only implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds nothing beyond that: it does not say whether attaching is reversible, whether it provisions a new branch/database or links an existing one, whether it consumes quota, or what side effects occur on the target project — all relevant for a non-idempotent mutation.

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?

It is a single short sentence with no filler and the key concept is front-loaded. Brevity here is under-specification rather than tight writing — the sentence is efficient but omits information the agent genuinely needs.

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

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

For a mutation tool with no output schema and no annotations covering anything beyond safety, the description should explain what attach produces and how the caller observes success. Instead it leaves the attach target, side effects, and expected result entirely undocumented, which is inadequate for this complexity level.

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

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

With a single parameter at 100% schema description coverage, the schema already carries the semantics (project_id or the session fallback from use_project). The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ("Attach" a "Neon Postgres database"), which is more informative than the bare name. However, it never states what the database is being attached to (a project, per the schema) or how this differs from the sibling detach_database, so an agent must infer the object relationship.

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

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

There is no when-to-use guidance at all: no mention of prerequisites (an existing project, a Neon provider setup), no indication of when to call detach_database instead, and no note on how this interacts with use_project-based sessions. The agent must derive usage from the parameter schema alone.

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 openWorldHint=false, so the agent knows this is an unconfined-but-sandboxed mutation surface. The description adds the useful context that execution is confined to the 'project sandbox', but says nothing about output capture (stdout/stderr/exit codes), timeout behavior, or what state a destructive command can affect.

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

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

Two short sentences with zero waste; the core action is front-loaded and the caveat follows immediately.

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

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

This is a destructive, four-parameter execution primitive with no output schema, yet the description never explains what a call returns or how failures are surfaced. Given the untyped `command` string and undocumented timeout semantics, an agent is left guessing on important operational details.

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% — only `project_id` is documented, while `command`, `cwd`, and `timeout_ms` have no schema text. The description contributes nothing about any parameter; it doesn't even state that `cwd` defaults to the project root or how `timeout_ms` interacts with `bash_await`.

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 — 'Run a shell command in the project sandbox' — which an agent can distinguish from file tools or preview tools. It doesn't explicitly differentiate itself from the sibling `bash_await` or `browser_run`, so sibling routing is only partially covered.

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 second sentence gives one useful exclusion: long-lived preview servers belong to the project run config, not a shell. However, there is no guidance on when to use `bash` versus `bash_await` for long-running work, nor any note about preferring `edit_file`/`write_file` for file changes.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that the call blocks until completion and yields output, but says nothing about what happens if timeout_ms elapses (error vs. partial output), which is the main behavioral risk for a blocking wait.

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 well-formed sentence, front-loaded with the action and its key. Nothing is wasted, though the brevity comes partly at the cost of the missing timeout detail.

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 low-complexity 3-parameter tool with no output schema, the description covers the core contract, but it leaves the timeout parameter and the shape of 'its output' (stdout, stderr, exit status) to inference.

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

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

Schema coverage is only 33% — project_id is documented in the schema while shell_id and timeout_ms have no descriptions. The description references shell_id but never explains that it comes from a prior background invocation, and timeout_ms (and its expiry semantics) is entirely unaddressed.

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 ('wait ... to finish') and resource ('background shell command') plus the keying parameter (shell_id). It implicitly distinguishes itself from the sibling `bash` tool by scoping to background commands, though it never names `bash` explicitly.

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

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

The phrase 'background shell command' implies the workflow (start something with bash, then await it), but there is no explicit pointer to the sibling that creates shell_ids and no when-not-to-use guidance (e.g., foreground commands already return synchronously).

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, destructiveHint=false and openWorldHint, so safety is largely covered. The description adds real value by disclosing the sandbox runtime and that screenshot('label') attaches PNGs to the result. It omits other behavior an agent needs: what a failing check returns, whether script errors surface as tool errors, and default timeout 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?

Three short sentences, front-loaded with the purpose, followed by the base_url default and the result-attachment detail. No filler or restatement 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?

With no output schema, the description only hints at return content via the screenshot attachment and says nothing about pass/fail reporting, console output, or timeouts. It also does not warn about side effects of arbitrary Playwright code in the sandbox, leaving meaningful gaps for a 5-parameter execution 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 40%, so the description must compensate. It clarifies base_url (omit to use localhost) and echoes the screenshot semantics of code, but leaves the required 'title' parameter and 'timeout_ms' completely undocumented in both schema and description.

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

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

Names a specific verb and resource: runs Playwright checks against the preview in a sandboxed Chromium. It implicitly separates itself from siblings like start_preview/get_preview by being the execution tool, but never names an alternative explicitly.

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

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

Gives one concrete conditional ('Omit base_url so it uses localhost'), which is useful usage guidance for a key decision point. However there is no statement of when to pick this over bash, get_logs, or bash_await for verification, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the meaningful detail that the created object is empty; it says nothing about overwriting an existing path, error behavior, or whether parent directories are created.

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 is arguably too terse rather than padded, so efficiency is high.

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 three-parameter creation tool with no output schema, the description leaves important behavior unspecified: what happens if the path already exists, whether intermediate directories are created, and what is returned on success. Annotations cover safety but not these mechanics.

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

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

Schema coverage is only 33% — only project_id carries a description — so the description must compensate, which it partly does by implying the file-vs-directory choice via "file or directory." The `path` and `directory` parameters still receive no explicit semantics such as relative vs absolute paths.

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 an empty file or directory." It clearly separates creation from siblings like write_file or upload_file by emphasizing "empty," but it never names an alternative to reinforce that distinction.

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 instead of write_file, upload_file, or edit_file, and no exclusions or prerequisites are given. The agent must infer from the word "empty" that content-bearing creation goes elsewhere.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered. The description usefully adds that a sandbox is provisioned ('wake its sandbox'), implying latency and resource creation, but says nothing about required permissions, idempotency on duplicate names, or whether the sandbox is ready on return.

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 is appropriately sized for a simple create tool, though it could spend one more clause on the sandbox side effect without becoming verbose.

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

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

No output schema exists, but the annotations plus the description cover the essentials for a create tool: what is created and that a sandbox is started. Missing only the return/preparation semantics and the optionality of the two parameters, which keeps it from a 5.

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% – only 'prompt' is documented in the schema ('Short description used for naming'), while 'name' has no description. The tool description adds no parameter information at all, notably omitting that both parameters are optional and how naming is derived from the prompt when name is absent.

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 ('Create a new Mythex project') and adds a distinguishing side effect ('wake its sandbox') that separates it from list_projects, get_project, and update_project. It does not explicitly name a sibling, so it falls just short of full differentiation.

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

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

Use is only implied by the verb 'create' – an agent can infer this is the starting point for a new project. No when-not guidance, no prerequisites, and no pointer to alternatives (e.g. import_project for existing code) is offered.

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

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

Beyond the annotations, the description discloses that access is view-only, that the recipient does not need a Mythex account, and that links are revocable. These are meaningful behavioral details for an open-world mutation tool, though it does not mention creation permissions or expiration 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?

Two short sentences, front-loaded with the core action and immediately followed by the key distinction from publishing. Every clause adds useful information with no 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 two-parameter, non-destructive sharing tool, the description covers the important concepts: external access, view-only permission, live preview target, and revocability. It could optionally say that a URL is returned, but the essential behavior 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?

Schema description coverage is 100%, and both parameters are documented there, including the purpose of name and the project_id/session fallback. The description adds no parameter-level detail 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 gives a specific verb and resource (create a share link) and precisely scopes it as a view-only link to the live preview for someone without an account. It also distinguishes the action from publishing, so an agent can separate it from publish_app and publish_readiness.

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

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

It explicitly says when this is appropriate (showing work in progress to an external viewer) and when it is not (not a publish). It does not name the sibling alternatives, but the usage context is clear enough for correct tool 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered by structured data. Beyond that, the description adds only the word 'or directory', leaving open whether directory deletion is recursive, whether it is reversible, and how conflicts or missing paths are handled.

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

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

One short, front-loaded sentence with no filler, which is structurally fine. The brevity here reflects under-specification rather than efficient communication.

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

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

For an irreversible destructive operation with a required undocumented path parameter and no output schema, the description omits what matters most: scope of deletion, recursion on directories, and failure behavior. The annotations supply the safety flag, but the operational details are absent.

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

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

Schema coverage is only 50%: project_id carries a description in the schema, but the required 'path' parameter has none, and the description does not clarify whether it is relative to the project root or absolute. With a low-coverage schema, the description needed to compensate and does 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 verb 'delete' and resource 'file or directory' are stated, but this is essentially a restatement of the title 'Delete file' with the addition of 'or directory'. It gives no basis for choosing it over the sibling storage_delete_object, which also deletes a stored object.

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

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

There is no when-to-use guidance, no mention of prerequisites (does the path need to exist? is a project context required?), and no pointer to alternatives such as storage_delete_object or delete_project. The agent must infer everything from the name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is largely covered. The description adds one useful qualifier — 'permanently' — signaling irreversibility, but says nothing about cascade effects (domains, deployments, env keys), confirmation requirements, or permissions.

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 short sentence with the key qualifier front-loaded alongside the verb. Efficiency is fine, but the brevity is partly under-specification rather than discipline.

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 permanent, destructive operation with no output schema and an undocumented required parameter, the description omits what else is removed, whether it can be undone, and how to identify the project — leaving an agent under-informed before an irreversible call.

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 lone parameter, project_id, is undocumented in both schema and description. The description does not say whether it accepts a name, slug, or opaque ID, nor where to obtain it (e.g., from list_projects).

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

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

States a specific verb and resource ('Delete a project'), clearly distinguishable from sibling deleters like delete_file and delete_share_link. It stops short of differentiating from related lifecycle tools such as update_project or unpublish_app, but the core purpose is unambiguous.

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

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

No guidance on when to use this versus alternatives such as unpublish_app or restoring via checkpoints, and no prerequisites or caveats are stated. The agent must infer entirely from the tool name and annotations.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context with '(stops working within seconds)', telling the agent that revocation propagates with a short delay rather than being instantaneous — useful for verifying 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?

One short sentence with the action front-loaded and the timing caveat in parentheses. Every clause earns its place and nothing is padded.

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

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

For a destructive, one-required-parameter tool with no output schema, the description covers the action and the propagation delay but omits what happens on an invalid/already-revoked share_id, whether project_id is required when a session is active, and what a successful response contains.

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

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

Schema coverage is only 50%, and the undocumented parameter is the required one: share_id has no schema description and the description says nothing about its format or how to obtain it. Only project_id carries any explanation, and that comes from the schema, not the description.

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: 'Revoke a preview share link'. The verb 'revoke' naturally distinguishes it from create_share_link and list_share_links, but no sibling is named explicitly, so it falls just short of a 5.

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

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

Usage is only implied — an agent infers it should call this to undo a share link. There is no guidance on prerequisites (obtaining a share_id, e.g. via list_share_links) or when an alternative would apply, so it stays at minimum-viable.

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, so safety is structurally disclosed. The description adds nothing about irreversibility, whether data is recoverable, required project state, or permission needs, and the "detach/delete" ambiguity leaves the actual consequence of the call unclear.

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?

It is a single short, front-loaded phrase with no filler, but that is brevity by omission rather than by discipline; the sentence is under-specified for a destructive 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 destructive, one-parameter operation with no output schema, the definition should say what is destroyed, whether it is reversible, and how to recover. None of that is present, so an agent cannot predict the outcome beyond the destructive flag.

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

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

Schema coverage is 100% and the single project_id property already explains the "or use session from use_project" fallback. The description contributes no additional parameter guidance, which is the baseline expectation when the schema is complete.

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

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

The description names a verb and resource ("Detach/delete the project database"), so the target is identifiable. But the slash conflates two operations with very different consequences, and it does not distinguish this from sibling delete_project or explain its relation to attach_database.

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 statement of when to use this versus attach_database, delete_project, or delete_file. The agent must infer scope and prerequisites entirely from 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds no behavioral context beyond its own name, such as what happens to existing objects, reversibility, or required permissions.

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 phrase with no wasted words. It is appropriately sized for a simple toggle, though it is minimally structured rather than richly informative.

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 annotations cover destructiveness and the schema fully documents the only parameter, so the tool is callable. However, for a destructive toggle the description should at least clarify the effect on existing storage or any 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?

The schema has 100% description coverage for the single optional project_id parameter, so it already explains the usage and the 'use_project' session fallback. The description adds no parameter meaning, but the schema 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 names a specific verb and resource: 'Disable app object storage.' An agent can distinguish this from most siblings, but it does not explicitly contrast with the complementary 'enable_storage' 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?

There is no guidance on when to use this tool versus alternatives such as 'enable_storage' or 'storage_delete_object.' The description gives no preconditions, exclusions, or routing information.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates data. The description adds real value by disclosing the uniqueness precondition and failure mode, which is not in the annotations or schema. It stops short of saying the file must already exist, whether the write is atomic, or what happens with an empty new_string.

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 sentence, front-loaded with the core behavior, and the failure condition parenthesized rather than buried. Nothing is wasted, though the extreme brevity leaves little room for the operational context an agent needs.

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

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

For a destructive mutation with 4 parameters, 25% schema coverage and no output schema, the description should do more. It omits whether the file must exist, whether an empty new_string deletes text, whether multiple occurrences could be handled another way, and what the call returns on success.

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%, with just project_id documented, so the description needs to compensate. It does explain the critical constraint on old_string (must be unique or the call fails), but says nothing about path semantics or what an empty new_string means.

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 — 'exact string replace in a file' — which tells an agent precisely what the operation does. It does not explicitly contrast with write_file or bash, but the 'exact string replace' framing is distinctive enough that differentiation is largely implicit.

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

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

No guidance on when to prefer this over write_file, bash, or rename_file. The only implied rule is the uniqueness failure condition, which is a constraint rather than a routing guideline.

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 merely restates the title and adds no behavioral context beyond what the annotations already imply. It does not disclose side effects, idempotency, permissions, or what happens to existing storage 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?

The description is extremely short and front-loaded, with no wasted words. It is efficient, though its brevity contributes to other gaps.

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 toggle with one optional parameter, annotations, and full schema coverage, the description is minimally adequate. However, it lacks prerequisites, expected effects, and guidance on project session 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?

Schema description coverage is 100%, so the single project_id parameter is fully documented in the schema. The description adds no parameter-level detail, which is acceptable given the schema's completeness.

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

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

The description states a specific verb ("Enable") and resource ("app object storage"), which clearly distinguishes it from the sibling disable_storage. It is clear but does not elaborate on scope or project relationship.

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, when not to use it, or how it relates to alternatives like disable_storage. The agent must infer usage from the name alone.

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, openWorldHint=false, and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing the primary return channel (a download link) and the conditional base64 fallback that changes response size and shape — genuinely useful behavior an agent cannot get from annotations.

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

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

Two short sentences, zero filler, with the action and format front-loaded and the return-value caveat immediately after. Every clause earns its place.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the url field and the base64 fallback. It stops short of covering size, streaming, or storage implications of a potentially large archive, so it is not fully complete for a one-parameter export tool.

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

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

Schema description coverage is 100% and the single project_id parameter is well documented in-schema, including the 'use session from use_project' alternative. The description adds no parameter guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (export the project) plus the concrete output format (tar.gz), which no sibling tool offers. An agent can distinguish it from get_project, import_project, or upload_file without opening the schema.

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

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

Usage is implied by the export semantics, but the description never says when to prefer this over alternatives such as reading individual files via read_file or glob_files, nor does it mention any prerequisites. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description goes beyond that by disclosing the returned shape (site_url as website, backends as per-service URLs) and the terminal states. With no output schema, this return-value context is genuinely additive. It stops short of stating failure modes or whether backends is absent while building.

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

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

Two short sentences, front-loaded with purpose and followed by field semantics; nothing is wasted. The telegraphic 'site_url is the website' phrasing is terse but readable.

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

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

For a two-parameter read tool with solid annotations this is close to sufficient, and the return-field gloss helps given there is no output schema. However, it never explains how to obtain deployment_id or how this differs from list_deployments/get_status, which an agent needs in order to call it correctly.

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

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

Schema coverage is only 50%: project_id is documented in the schema (including the use_project session alternative) while the required deployment_id has no description anywhere. The description discusses response fields but says nothing about either input, so it fails to compensate for the coverage gap on the one mandatory parameter.

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 ('Get deployment status') plus the status transitions it reports (BUILDING → LIVE / FAILED), so an agent knows exactly what comes back. It never names list_deployments or get_status, so differentiation from closely related siblings is left to inference.

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 status lifecycle hint implies a polling/verification use case, but there is no explicit statement of when to call this versus list_deployments (find a deployment) or get_status. No prerequisites, no note on where deployment_id comes from, and no 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say what 'healthy' means (HTTP reachability? process up?), whether the check is synchronous or has timeouts, or what happens when no preview is running.

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

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

A single front-loaded sentence with no filler — structurally sound. Its brevity is appropriate, though in this case it borders on under-specification rather than efficiency.

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 carries the burden of explaining the return value, and it doesn't — an agent cannot tell whether it gets a boolean, a status string, or diagnostic details. Combined with the undocumented port parameter, the definition is too thin 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 coverage is only 50%: project_id is documented in the schema, but port has no description at all. The description only echoes 'preview port' without clarifying whether it's the local dev port, the preview-assigned port, or how it relates to project_id / the use_project session.

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 ('check') and resource ('preview port health'), which is clearer than the title alone. It does not, however, differentiate itself from adjacent siblings such as get_preview, get_status, or get_services, which an agent could plausibly confuse it with.

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 indication of when to call this versus get_preview or get_status, nor any prerequisites (e.g., must a preview be started first). The agent must infer usage entirely from the name and one-line purpose.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the 'recent/tail' scoping nuance; it says nothing about whether logs stream, truncate, or return empty when no preview is active, which is meaningful for a log-fetching 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 short phrase with the key scoping detail ('recent', 'tail') front-loaded and no filler. It is efficient, though so terse that useful context is omitted rather than wasted.

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

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

For a tool with zero required parameters and no output schema, the description leaves important gaps: it does not explain the SSE/streaming nature implied by timeout_ms, what happens when no preview exists, or what the returned log format looks like. The agent is under-informed about invocation context despite the simple 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 description coverage is 100%, so both parameters (project_id, timeout_ms) are already documented, including the session fallback. The 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?

States a specific verb ('Fetch') and resource ('recent preview logs'), and '(tail)' scopes it to the newest entries rather than full history. It is clearly distinct from siblings like get_preview, get_status, or get_health, though it does not explicitly name those alternatives.

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

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

The description gives no when-to-use guidance, no prerequisites (e.g. must a preview be running?), and no mention of alternative tools for status or health checks. The agent must infer usage entirely from the title and parameter names.

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 say readOnlyHint=false and destructiveHint=false, and the description usefully confirms the side effect (starting the preview) while explaining the meaning of the healthy:false field in the response. With no output schema, that explanation of return-value semantics adds real value. It still omits whether startup is slow or blocking, and how it relates to start_preview.

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, zero filler, with the action and the returned-value caveat both front-loaded. Every 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 single-parameter tool with annotations and no output schema, the description covers the action, the return URL, and the healthy flag. It is still incomplete on the key ambiguities: how this differs from start_preview and what happens on a slow or failed preview start.

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

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

Schema description coverage is 100% and there is a single optional project_id already documented in the schema, including the 'or use session from use_project' note. The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

The description gives a concrete verb and outcome: start the preview if needed and return the public URL. That is clearer than the name 'get_preview' alone, which suggests a read. However, it never distinguishes itself from the sibling start_preview, so an agent cannot tell from the text which of the two to call.

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?

'Start the preview if needed' implies idempotence and that a prior start_preview call is unnecessary, which is mild guidance. But there is no explicit when-to-use, no exclusion, and no mention of start_preview, get_status, or get_health as alternatives, despite several plausible 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing further - no statement about behavior when the project does not exist, no session-vs-id precedence, no note on what is returned.

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 words, so there is no waste, but the brevity comes from under-specification rather than discipline. There is nothing front-loaded because there is essentially nothing there.

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

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

For a simple read tool the annotations and schema cover the mechanics, but the description leaves open what "details" includes and how the optional project_id interacts with an active session. Nothing is contradicted, but an agent gets no help deciding when this tool is the right call.

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

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

Schema coverage is 100% and the single parameter already documents the "or use session from use_project" fallback, so the schema carries the semantic load. The description contributes nothing beyond that, which is the baseline case for a one-parameter tool.

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 ("Get project details"), so the basic intent is clear. However, it does not distinguish this from closely related siblings such as list_projects, get_status, or use_project, nor does it say what "details" actually comprise.

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 indication of when to use this tool versus list_projects, use_project, or get_status. Any guidance about the session fallback appears only in the parameter schema, not in the description.

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 the specific behavioral constraint that it lists 'running' services. The annotations already provide safety context (readOnlyHint, destructiveHint), so the description provides moderate, focused value.

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

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

The single sentence is highly efficient, relevant, and front-loaded, achieving maximum communication with minimal 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?

Given the simple structure and lack of an output schema, the description is adequate. It provides the necessary scope (running preview services) without over-explaining what is already defined in the input 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?

Since schema description coverage is 100%, the schema covers all parameter details. The description merely reiterates the function and does not add any meaningful context to the parameter `project_id`.

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 is clear and uses a specific verb ('List') and resource ('preview services'). It helps distinguish the action, though it doesn't explicitly name a sibling tool it differs from.

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 no guidance on when to use this tool versus alternatives like 'get_preview' or 'list_deployments.' It only specifies the state of the services it handles (running).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description contributes that the result bundles status, services, and preview URLs, which is useful return-content context, but says nothing about freshness, errors when no sandbox is running, or shape of the response.

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?

It is only seven words with zero waste, but it is an under-specified fragment rather than a front-loaded sentence. Brevity here comes at the cost of clarity, not from efficiency.

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

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

There is no output schema, so the description carries the burden of explaining what comes back, and a three-noun list is thin for a tool that aggregates status, services, and preview URLs. It also does not address the optional project_id or behavior when no project context exists.

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

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

Schema description coverage is 100% and the schema already explains project_id including the 'or use session from use_project' fallback. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The phrase 'Sandbox status, services, and preview URLs' names the resource and the kinds of data returned, which is more informative than the title alone. But it is a noun fragment with no verb and no differentiation from siblings like get_health, get_services, get_preview, and get_project, several of which appear to overlap 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?

No indication of when to call this versus get_health, get_services, or get_preview, nor any note about prerequisites such as needing an active project. The agent must infer the choice entirely from sibling names.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), but the description says nothing about the GitHub auth/token requirement, what happens if a repo is already linked, or whether the repo is validated. For an open-world mutation, that 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?

A single compact sentence with the key entity and identifier format front-loaded. No padding, though it is arguably too terse for the operation's complexity.

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

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

With 4 parameters, two undocumented, no output schema, and an open-world mutation, the description leaves the agent without enough to call confidently — especially regarding branch selection and the effect of re-linking.

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?

Description only restates the repo format already documented in the schema; branch and base_branch (half the parameters, 50% coverage) get no explanation in either place. Nothing is added about which branch is tracked by default.

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

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

States a specific verb (link) and resource (a GitHub repo identified as owner/name) against the project entity. Clear on its own, though it does not distinguish itself from near siblings such as github_sync or github_pull.

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 indication of when this should be used versus github_sync, github_status, or the project-creation/import tools. The agent must infer that this is a one-time setup action.

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 openWorldHint=true, so safety is covered. The description usefully implies it only returns a link rather than mutating the repo, but leaves unexplained what 'Mythex branch' refers to and what happens when no repo/branch is linked.

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 short sentence is appropriately sized and front-loaded, but brevity here reads as under-specification rather than economy — the one clause that needs explanation ('Mythex branch') is left opaque.

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

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

There is no output schema, yet the description does not say what the returned URL looks like or whether it is a compare view vs a PR-creation link. For a tool whose whole output is a URL, that gap matters, and prerequisites are unstated.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents project_id fully. The description adds nothing about the parameter, which is the baseline expectation.

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 verb/resource ('Get a compare/PR URL') is present, but it is ambiguous whether the tool merely builds a link or actually opens a pull request, and the phrase 'the Mythex branch' is unexplained and appears hardcoded. Nothing distinguishes it from siblings like github_pull or github_link_repo.

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 on when to call this versus github_pull, github_status, github_link_repo, or github_sync, all of which live in the same namespace. There are no stated prerequisites (e.g. a repo must already be linked).

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

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

Annotations already declare this as destructive and open-world, but the description adds no details about what gets overwritten, whether local changes are affected, or what permissions are needed. It only restates the pull action and target branch.

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 short sentence with no waste and the action is front-loaded. It is appropriately sized for a simple pull operation.

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

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

For a destructive mutation with no output schema, the description is too thin: it does not explain prerequisites, effects on local state, or what success looks like. Annotations cover safety flags but the description should carry more operational context.

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

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

Schema description coverage is 100%, so the single project_id parameter is already documented in the schema. The description does not mention project_id or session fallback, but with full schema coverage the baseline is 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 and resource: 'Pull from the linked GitHub base branch.' It is clear what operation is performed, though it does not explicitly distinguish this from the sibling tool github_sync.

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 no guidance on when to use this tool, when not to use it, or how it differs from alternatives such as github_sync or github_status. The only implied prerequisite is that a repository is already linked.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only the scope hint that both connection state and linked-repo state are reported; it says nothing about behavior when no repo is linked, no auth requirements, or what the response looks like.

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

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

Five words with zero padding and the subject front-loaded, but it is under-specified rather than concise – there is no wasted text because there is almost no text. Brevity here comes at the cost of usability.

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 genuinely simple (one optional param, read-only, open-world), so a short description is defensible. However, with no output schema, the description is the only place a caller could learn what 'status' returns, and it does not say.

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?

Only one optional parameter and schema coverage is 100% – the schema itself explains project_id and the session fallback via use_project. The description contributes no additional parameter meaning, so the baseline of 3 applies.

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

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

The fragment 'GitHub connection + linked repo status' does identify the resource and that it is a status read, which separates it from the generic get_status. But it is a noun phrase with no verb and no explicit contrast to siblings like github_link_repo, github_sync, or github_pull, so the agent must infer which GitHub tool answers a status question.

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 call this versus github_link_repo, github_sync, or get_status, and no stated preconditions (e.g., does it need a linked repo first?). The single schema hint about project_id/session is the only routing help present.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description only restates that commits are pushed to the linked branch; it says nothing about authentication needs, conflict/force-push behavior, or what happens if no repo is linked — the kind of context that would earn credit over 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?

A single tight sentence with the key scope ('Mythex commits', 'linked branch') front-loaded and no filler. Its brevity is what leaves gaps elsewhere, but as structure it is 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?

For a mutation tool touching a remote GitHub repo with no output schema and half of its parameters undocumented, this is too thin. An agent is left uninformed about required setup, the purpose of the message parameter, and what a successful push returns.

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%: project_id is documented in the schema while 'message' has no description anywhere. The description does not compensate — it never mentions the commit message parameter or any format/constraint on either input, so an agent must guess what 'message' means.

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

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

The description gives a specific verb (push) and resource (Mythex commits to the linked GitHub branch), which is enough to distinguish it from github_pull and github_link_repo. It stops short of naming those siblings explicitly, so the differentiation is inferred rather than stated.

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

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

The phrase 'linked GitHub branch' implies the prerequisite that a repo must already be linked via github_link_repo, but there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as github_status or github_pull.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the listing covers 'all project file paths' and that filtering is optional, but says nothing about return shape, ordering, or size limits for large projects.

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

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

A single tight sentence with the core action front-loaded and no filler. The trailing parenthetical is slightly awkward but does not bloat the definition.

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 read-only tool with no output schema and adequate annotations, the description is minimally viable. It is still missing the disambiguation an agent needs to choose it over list_files/search_files, which matters given the crowded sibling set.

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 both parameters are documented in structured data, establishing the baseline of 3. The description restates the optional nature of the filter but adds no format or matching semantics beyond 'substring or glob-ish filter' already 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?

States a concrete verb and resource: 'List all project file paths', with the optional substring filter scoped. However, it does not differentiate itself from the closely-named siblings list_files and search_files, both of which plausibly do something similar.

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 statement of when to use this versus list_files or search_files, and no prerequisites or exclusions. The only hint is the parenthetical 'optional substring filter', which implies but does not guide 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?

Annotations already declare this as destructive and open-world, but the description does not explain what is destroyed or overwritten (existing project files? entire project?). It also omits whether importing into an existing project replaces content, and no permission or scope requirements are mentioned.

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

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

It is a single front-loaded sentence with no filler. It is efficient, but the extreme brevity for a destructive import operation makes it under-specified rather than optimally concise.

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

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

For a destructive, open-world mutation with three parameters, low schema coverage, and no output schema, the description is far too thin. An agent is left without the overwrite semantics, archive format behavior, or target project requirements needed to invoke it safely.

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?

Only project_id is documented in the schema, leaving data_base64 and format undocumented. The description explains that data_base64 holds a base64 archive, but says nothing about the format parameter's enum values or whether format 'auto' is detected from content.

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

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

The description gives a specific verb and resource ('Import a base64 archive into the project'), so the action is immediately understood. It does not differentiate itself from close siblings such as upload_file or create_project, which also introduce content into a project.

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 instead of upload_file, create_project, or export_project. Prerequisites such as whether the target project must already exist, and when to prefer format 'auto', are left entirely unstated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds only that the checkpoints are git-based; it says nothing about ordering, result size, or how checkpoints relate to restorable state, which is the main behavioral fact an agent would want.

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 short, front-loaded sentence with no waste. Its brevity is close to under-specification, but nothing is redundant or buried.

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

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

For a simple read-only list tool with full schema coverage and annotations covering safety, the description is minimally adequate. It omits what a checkpoint represents and any ordering or scoping detail that would help an agent decide 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%, and the single parameter's description already explains the project_id-or-session fallback. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('git checkpoints') scoped to a project, which is clearly distinguishable from mutation siblings like restore_checkpoint. It does not explicitly name siblings or explain what a checkpoint contains, so it stops short of 5.

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

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

No guidance on when to list checkpoints versus restoring one, no mention of pagination/limits, and no hint that project_id may be omitted in favor of the session from use_project. The agent must infer all of this.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no statement of result shape, ordering, scoping to the active project, or empty-result 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?

Two words, zero waste and maximally front-loaded, but this is brevity by omission rather than disciplined concision. It is not padded, yet it fails to earn its place as a usable definition.

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

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

Annotations and schema cover the safety profile and the one parameter, and there is no output schema, so some burden is lifted. Still, for a list tool in a dense 60-sibling namespace, the absence of any scoping or return-value context leaves the definition inadequate.

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

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

Schema description coverage is 100% and the single parameter's description even explains the 'or use session from use_project' fallback. The tool description neither repeats nor extends this, so baseline 3 applies for a one-param tool whose schema does the work.

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?

Tautological: description restates name/title.

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 call this versus get_deployment (single lookup) or list_projects, and no mention of the project_id-or-session prerequisite implied by the schema. The agent must infer all selection logic from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds the 'custom domains' scope but does not disclose return format, pagination, or authentication requirements, which is acceptable given 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 a single front-loaded sentence with no redundant or filler content. Every word contributes to stating the operation and scope.

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

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

For a simple read-only list tool with full schema coverage and clear annotations, the description is sufficient to call it correctly. It does not explain return values, but no output schema exists and the list operation is self-explanatory.

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

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

Schema coverage is 100%, and the schema itself documents project_id including the session fallback via use_project. The description only restates 'for the project' and adds no parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('List') and resource ('custom domains') scoped to the project. It is clearly distinguishable from sibling mutation tools like add_domain and remove_domain, though it does not explicitly name alternatives.

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

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

The phrase 'for the project' implies the context in which to use the tool, but there is no explicit guidance on when to prefer it over alternatives such as get_project or verify_domain. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one non-obvious behavioral guarantee that annotations do not carry: values are never returned, which both sets agent expectations and signals the tool is safe to call without exposing secrets. Ordering, pagination and empty-list behavior remain 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?

One sentence, front-loaded with the action, with the most decision-relevant constraint (keys only, never values) in parenthetical emphasis. Nothing is wasted and nothing important is buried.

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

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

For a one-optional-parameter read-only tool with no output schema, the description covers the essentials: it returns key names and only key names, which is effectively the return-value contract. Minor gaps (scope of the listing, ordering, behavior with no session) are low-risk given the annotations and full schema coverage.

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

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

Schema description coverage is 100% and the single project_id parameter is fully documented in the schema, including the 'or use session from use_project' fallback. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (list environment variable keys) and adds a sharp scope qualifier: KEYS only, never values. That qualifier is what separates it from the sibling write-side tool set_env, so an agent can tell the difference without opening the schema, though no sibling is named explicitly.

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

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

There is no when-to-use or when-not-to-use guidance. The description never says to call this before set_env, nor how it relates to project_id vs the session established by use_project, which is the one real decision an agent faces here. The keys-only phrasing only hints at intent.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the bare notion of listing within a directory and says nothing about recursion, pagination, hidden files, or ordering behavior, so it barely clears the lower bar set 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?

The single sentence is front-loaded and free of noise, but its brevity reflects under-specification rather than efficient communication. It withholds details the agent needs to call the tool correctly.

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 and one undocumented parameter, the description should carry more weight. It omits the meaning of the default empty path, the role of project_id/session, recursion behavior, and return shape, leaving material gaps for a tool with two parameters and several sibling alternatives.

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

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

Schema coverage is only 50%: project_id is documented, but path has no description and defaults to an empty string. The description does not explain what an empty path means, whether it is relative or absolute, or how the project/session context affects the listing, so it fails to compensate for the coverage gap.

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

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

The description states a clear verb and resource: list files in a directory. It does not distinguish this from closely related siblings such as glob_files, search_files, or read_file, so it falls short of the sibling-differentiation bar for a 5.

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

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

There is no guidance on when to use this tool versus glob_files, search_files, or read_file. The agent must infer that this is a plain directory listing rather than a pattern search or content read.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is fully covered structurally. The description adds only the ownership scoping ("the user's"), and says nothing about result volume, ordering, or pagination behavior — which is the main open question for a list 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 short sentence with zero filler, front-loading the verb and resource. It is efficient, though so terse that efficiency shades into under-specification rather than a deliberate structure.

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

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

For a no-arg read tool with annotations and no output schema, the description is minimally adequate. It leaves open what the listing contains (counts, ordering, whether all projects or a truncated set), which is exactly the context an agent would want before choosing between this and get_project.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to compensate for. Baseline 4 applies; no parameter meaning is missing because no parameters exist.

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 (projects) with the scope qualifier "the user's," which distinguishes it from project-scoped tools like get_project or update_project. It stops short of explicitly naming any sibling (e.g., get_project for a single project), so the differentiation is inferable rather than stated.

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

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

The description gives no when-to-use condition, no mention of when to prefer get_project for a single project, and no prerequisites. An agent must infer the usage entirely from the verb and the surrounding tool 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds little beyond noting that these are 'preview' share links; it does not describe return format, pagination, or authorization 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?

A single six-word sentence that is front-loaded and free of waste. It communicates the action and scope without unnecessary padding.

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

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

For a simple read-only list operation with full schema coverage and explicit annotations, the description is largely sufficient. It could mention the optional project_id/session convention, but that is already in the schema.

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

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

Schema coverage is 100%, and the schema itself explains that project_id can be omitted in favor of a session from use_project. The description adds no parameter detail, but the baseline is 3 when the schema fully documents the single parameter.

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 ('preview share links') scoped to the project. It clearly differs from create_share_link and delete_share_link by its listing action, though it does not explicitly name those siblings.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance, and does not mention alternatives such as create_share_link or delete_share_link. Usage is only implied by the verb '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?

Annotations already declare readOnlyHint=false and openWorldHint=true, so the bar is lower, yet the description adds real value: publishing is asynchronous ('returns immediately'), status transitions to LIVE or FAILED, and a frontend+API app is split into a site plus one backend per server service with /api routed to the backend. It does not mention idempotency, re-publish behavior, or what identifier is returned to poll.

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 tightly written sentences, front-loaded with the action and async contract before the topology detail. Nothing is padded, though the topology sentence is only relevant to a subset of apps.

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

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

With no output schema, the description does the right thing by explaining the async contract and the status terminal states. It stops short of saying what is returned (deployment id/slug) or how to poll (get_deployment), which is the one remaining gap for a caller.

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 both parameters (slug, project_id) are fully documented in the schema, making 3 the baseline. The description adds no parameter-level detail beyond implying a public URL/subdomain exists, so it neither compensates for nor improves on 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 gives a specific verb and resource ('Publish the app to a public URL') and clarifies the resulting deployment semantics. It is clearly distinguishable from siblings like unpublish_app or publish_readiness, though it never names those alternatives explicitly.

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

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

Usage is only implied by the verb 'publish'; there is no statement of preconditions, no mention of publish_readiness as a prerequisite check, and no pointer to get_deployment/list_deployments for tracking the build. An agent can infer intent but must guess the 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description usefully goes further by disclosing the failure shape ('ready:false with topologyHint names each service missing its deploy config') and the meaning of live.services, which tells the agent what to do with an unready result. It omits any note on permissions or what a fully-ready payload 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?

Three short sentences, purpose front-loaded, no filler. The middle sentence is dense field notation (ready/topologyHint) that reads slightly like schema shorthand, but nothing is wasted.

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

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

For a read-only one-parameter check with no output schema, the description covers the important outcomes: the boolean readiness flag, the blocking-service hint, and the published-surfaces list. It is nearly complete; only a hint about what to call next on failure 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 the single project_id parameter carries a description plus the 'use session from use_project' fallback. The description adds nothing about the parameter, so baseline 3 applies — the schema does all the work.

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: 'Check if the project is ready to publish.' It is clearly a pre-flight diagnostic, distinguishable in spirit from publish_app (which performs the publish) and get_status/get_services, though no sibling is named explicitly.

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

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

Usage is only implied by the name and the phrase 'ready to publish' — an agent can infer it should be run before publish_app, but the description never says when to use it, when not to, or which alternative (get_status, get_deployment) answers a different question.

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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The parenthetical adds one genuinely behavioral note: binary content is returned base64-encoded. The description still says nothing about file-size limits, behavior when the path is missing, or how project scoping affects the read.

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

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

It is a single short sentence with the core action front-loaded, and there is no filler. Nothing can be trimmed without losing information.

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

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

For a simple read tool with strong annotations and no output schema, the description is minimally adequate. An agent still lacks two things: how project_id interacts with path resolution, and what the return value looks like, namely a content string with a specified encoding.

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%): only project_id is described in the schema, while path and the encoding enum are bare. The parenthetical partially explains encoding ('text, or base64 for binary'), but path semantics (absolute versus project-relative) remain undocumented in both places.

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 a file'. It does not distinguish from the nearby list_files, glob_files, or search_files, but the intent is unambiguous. This is clear enough that an agent can select it, but it offers no explicit differentiation from its siblings.

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

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

The description gives no guidance on when to use this tool versus alternatives such as list_files or glob_files, and it states no prerequisites. The parenthetical about text versus binary is the only hint about usage 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known, but the description adds nothing beyond that: no statement about what is destroyed (DNS records, verification state, custom-domain routing), whether it can be undone, or how long removal takes to propagate. It essentially restates the title.

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 single short phrase is front-loaded and wastes no words, but at four words it is nearly a restatement of the title rather than an informative sentence. This is under-specification rather than excessive length.

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

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

For a destructive, open-world mutation with no output schema and one undocumented required parameter, the description should explain irreversible effects, the domain_id format, and the project scoping fallback. None of that is present, leaving the definition inadequate for correct invocation.

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

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

Schema coverage is only 50%: project_id is documented in the schema, but domain_id has no description at all, and the description does not compensate by saying whether it accepts a domain name versus an opaque id or how to obtain it. An agent must open the schema and still guess at domain_id's expected format.

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 plus resource ("Remove a custom domain"), which is enough to distinguish it from add_domain, list_domains, and verify_domain by name alone. It does not, however, explicitly differentiate itself from set_primary_domain or explain the relationship to the broader domain lifecycle.

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 versus alternatives such as set_primary_domain, verify_domain, or simply leaving the domain unverified. No preconditions (e.g., must the domain be unverified or non-primary first) and no note about irreversibility are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so safety is partly covered. The description usefully reveals that the operation can also move a file, not just rename it, but it omits important mutation behavior such as what happens if the destination exists or whether directories are created.

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 extremely short and front-loaded with the core action. However, its brevity edges into under-specification given the mutation and path semantics involved.

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

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

For a mutation tool with no output schema and incomplete parameter documentation, the description should explain path semantics, overwrite behavior, and error conditions. It does not, leaving the agent with too little context to call the tool confidently beyond the simplest case.

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 33%, with just project_id documented. The description does not clarify the semantics of 'from' and 'to' — for example, whether 'to' is a filename only or a full path, or how moving across directories works. It adds minimal meaning beyond the property names.

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

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

The description states a specific verb ('rename') and resource ('file') and adds a second capability ('move'). No sibling tool duplicates that exact rename/move behavior, so the purpose is clear, though it does not explicitly differentiate itself from edit_file or write_file.

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

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

There is no indication of when to use this tool versus alternatives such as edit_file, write_file, or create_path, nor any prerequisites such as project/session context despite the project_id parameter. The agent must infer everything about 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description confirms the operation is file restoration, but adds nothing about what is overwritten, whether untracked/added files are removed, or whether it is reversible — the key questions for a destructive restore.

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

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

A single front-loaded sentence with no waste, but it is under-specified rather than economical — there is room for one more clause on scope or the sha requirement without becoming verbose.

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

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

For a destructive, three-parameter mutation with partial schema coverage and no output schema, the description leaves the caller guessing on the required identifier source and the files_only switch. It is too thin for the complexity of the operation.

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

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

Schema description coverage is only 33%: project_id is documented, but git_sha and files_only are bare. The description explains neither — notably it does not say what files_only=true excludes (e.g. restore files but not project config), which is the main behavioral choice in the call.

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 (restore) and resource (project files at a git checkpoint), which is enough to distinguish it from list_checkpoints and write_file. It stops short of naming how the checkpoint is chosen or how it relates to 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?

No guidance on when to use this instead of list_checkpoints, import_project, or plain file edits, and no prerequisite like 'obtain git_sha from list_checkpoints first'. The agent must infer usage entirely.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no mention of search scope, result limits (the 'max' param), performance, or whether hidden/binary files are searched.

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

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

Four words with zero padding and the key noun front-loaded, so nothing is wasted. However, the extreme brevity is under-specification rather than discipline given six parameters and no sibling routing — the size itself is the problem.

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?

Nothing about scope, matched-output format, or the interaction of query with regex/case_insensitive/include is documented, and there is no output schema to cover return values. For a six-parameter tool with 17% schema coverage, the definition is not complete enough to invoke confidently without trial and error.

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 17% — five of six parameters (query, max, regex, include, case_insensitive) have no schema documentation, and the description supplies no semantics for any of them. '(grep)' faintly implies pattern/regex matching but does not explain what 'include' filters, what 'max' defaults to, or that 'query' is content rather than a filename.

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 verb-plus-resource phrase 'Search file contents (grep)' clearly states a content-search operation, and the '(grep)' gloss distinguishes it from filename-pattern siblings like glob_files and plain listing via list_files. It does not explicitly name those siblings, so it falls short of a 5.

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

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

There is no guidance on when to use this versus glob_files (filename matching), read_file (reading a known file), or bash/grep. The agent must infer the alternatives and the selection conditions entirely on its own.

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, openWorldHint=true, and destructiveHint=false, so the safety and open-world profile is known. The description adds one genuinely useful trait beyond that — 'best-effort', signaling unreliable results — but says nothing about rate limits, latency, or what form results take.

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 compact phrase with no filler and the core capability front-loaded. It is under-specified rather than bloated, so the terseness costs it little here.

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 carries the burden of explaining return values, and it does not — an agent cannot tell whether it gets icon names, URLs, or rendered assets. For a simple two-parameter tool this is the main remaining gap, and the undefined 'query' parameter compounds 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 description coverage is only 50%: the required 'query' parameter has no description at all, and the description does not compensate by explaining what a query should contain (icon style, keyword, library). Only project_id is documented, and that comes from the schema, not the description.

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

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

The description names a verb ('search') and resource ('icons'), but hedges with 'Suggest icon names / search icons', leaving ambiguous whether the tool returns icon names, identifiers, or image assets. It does not distinguish itself from the adjacent search_photos/search_videos tools, which have nearly identical naming patterns.

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

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

There is no explicit when-to-use or when-not guidance, and no named alternative. The parenthetical '(best-effort via web search)' hints that this is a fallback mechanism but never says what it is a fallback to (e.g., web_search or a bundled icon 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=true, openWorldHint=true, and destructiveHint=false, and the description adds essentially nothing new – 'Unsplash' merely restates the open-world external source. It says nothing about rate limits, result counts, pagination, or whether results are cached/attributed.

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

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

Four words, front-loaded, zero waste. Its brevity is efficient, though it borders on under-specification handled in other dimensions.

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-parameter tool with no output schema and an undocumented required query, the description should at least state what query accepts and roughly what comes back. It leaves the agent to guess both.

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 required 'query' parameter is completely undocumented in both schema and description, leaving only 50% coverage overall. The description does not explain whether the query is free text, keywords, or identifiers, so it fails to compensate for the schema gap.

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

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

States a concrete verb (Search) and resource (stock photos) plus the provider (Unsplash), which lets an agent separate it from search_icons, search_videos, and generate_image. It stops short of describing search scope or result type, so it is clear but not richly differentiated.

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

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

There is no when-to-use or when-not-to-use guidance and no naming of alternatives such as search_icons or generate_image. Usage is only implied by the word 'Search'.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful fact: the results come from Pexels, i.e. a third-party stock provider with its own catalogue. It says nothing about pagination, result limits, or licensing.

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

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

Four words, front-loaded verb, zero waste. It is efficient rather than padded; the brevity is only a problem because it leaves gaps rather than because it wastes space.

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

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

For a simple read-only search this is thin: nothing on query syntax, on how many videos come back, or on whether results are cached/attributable. With no output schema, the description is the only place an agent could learn the shape of the response, and it does not.

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 50%: project_id is documented in the schema, but the required 'query' parameter has no description anywhere. The description does not compensate by explaining whether query is free-text keywords, a phrase, or supports filters, which is the single most important thing an agent needs here.

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 ('Search stock videos') and names the underlying provider (Pexels), so an agent can tell it apart from search_photos and search_icons by the media type alone. It stops short of explicitly contrasting itself with those siblings, but the resource noun does most of the work.

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 reach for this versus web_search or web_fetch, nor any note that this is an external stock-media library rather than a web crawler. The agent must infer usage entirely from the tool name.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds genuinely new behavior: values are encrypted at rest and not echoed back, and the operation merges rather than replaces. It does not state that an existing key's value is overwritten by a set, which is the main remaining gap given destructiveHint=true. 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?

A single tight sentence with the operation front-loaded and the security caveat in a parenthetical - no wasted words. It is arguably too terse for a destructive mutation, but nothing in it is filler.

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

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

With no output schema and only two parameters, the description covers the essentials, but for a destructive write tool it omits overwrite semantics, whether a project must be active (session vs project_id), and any confirmation/irreversibility note. Adequate but with clear gaps for a mutation.

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

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

Schema description coverage is 50%: project_id is documented in-schema, but the vars array and its key/value items have no descriptions anywhere. The description's note that values are encrypted and not echoed back does add meaning for the 'value' field, but it says nothing about key naming rules, duplicate keys, or how merge conflicts resolve.

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

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

States a specific verb pair (set/merge) and resource (project secrets / env vars), which goes beyond the bare title. It is clear what the tool does, but it never names its read-side sibling list_env_keys or otherwise differentiates itself from the other project-mutation 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?

'Set/merge' implies additive behavior (existing keys are retained rather than wiped), which is a usage-relevant signal. However, there is no explicit when-to-use/what-not-to-do guidance and no pointer to list_env_keys for inspection before writing; the agent must infer 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?

Annotations only state readOnlyHint=false and destructiveHint=false. The description does not say what happens to the previously primary domain, whether the target must first be verified or attached, or whether DNS/routing changes propagate — all material 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?

Four words with no padding, but the brevity comes from under-specification rather than efficiency. It is front-loaded but contains almost no 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?

A mutation tool with no output schema, half its parameters undocumented, and only basic annotations — the description supplies none of the missing context an agent needs to invoke it safely or 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 50%: project_id is documented in the schema, but domain_id is an undescribed string. The description adds no clarification of either parameter, such as where domain_id comes from (e.g., list_domains).

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?

"Set primary custom domain" restates the tool name and title almost verbatim, adding only the word "custom". It conveys a mutation on a domain resource, but nothing tells an agent how this differs from add_domain, verify_domain, or list_domains.

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 call this versus the other domain tools in the sibling set. An agent must infer that this switches which existing domain is primary, rather than adding or verifying one.

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 destructiveHint=true annotation already signals mutation risk, and the description adds useful behavioral context: it writes .mythex/run.json, starts a preview, and specifies the expected web service port. It does not explicitly state whether existing run.json content is overwritten, so it is strong but not exhaustive.

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

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

The description is dense but front-loaded with the action and side effect, then moves through port details, config shape, deploy requirements, and API proxy behavior. Every sentence contributes operational information without filler.

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

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

For a config-writing mutation tool with no output schema, the description supplies the key context an agent needs: what file is written, that a preview starts, the expected service structure, deploy shapes, and the API proxy convention. Safety is covered by the destructiveHint annotation, and parameters are covered by the schema.

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

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

Schema description coverage is 100%, so the schema already documents the two parameters. The description adds meaningful semantics beyond the schema by explaining the services array shape, deploy requirements for static vs server services, and the port/proxy setup.

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: 'Write .mythex/run.json and start the platform preview.' It also distinguishes this tool from using a shell for long-lived app servers, so an agent can identify the right tool without ambiguity.

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

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

It explicitly says long-lived app servers belong here rather than in a shell, giving a clear use case and alternative. It does not explicitly compare against siblings such as start_preview for simpler preview needs, so it falls short of full 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the config-file source, which is real context, but says nothing about what gets spawned (ports, processes), reversibility, or failure behavior when run.json is absent. With annotations carrying the safety burden, a 3 fits.

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

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

A single front-loaded sentence with no filler; the config path is the only extra detail and it earns its place. Slightly short of 5 because brevity here borders on under-specification rather than precision.

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

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

For a one-optional-param mutation tool with no output schema, the description covers what the tool does and where config comes from. It is still missing prerequisites (run.json must exist, project context via use_project), what 'start' produces, and the relationship to set_run_config and stop_preview, which an agent would need before calling it safely.

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%: the single optional project_id is fully documented in the schema, including the 'use session from use_project' alternative. The description never mentions project_id, so it adds nothing beyond the schema, and 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?

Names a specific verb ('Start') and resource ('preview services'), and adds the config source '.mythex/run.json' so the agent knows what drives the start. It implicitly contrasts with get_preview and stop_preview, but never names them, so the distinction comes from the verb rather than from explicit differentiation.

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

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

The '.mythex/run.json' reference hints that configuration must exist first, but there is no explicit when-to-use, no prerequisite statement (e.g. run set_run_config/use_project first), and no mention of stop_preview as the counterpart. Usage must be inferred from the verbs in 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — it does not say whether stopping is reversible via start_preview, whether running workloads are terminated, or whether data/state is preserved.

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?

It is a single short fragment with no waste, but that brevity comes from under-specification rather than discipline. Three words cannot front-load any decision-relevant 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 state-changing lifecycle tool with no output schema, the description should clarify the effect on the project (does the preview URL die, is the config retained, can it be restarted). None of this is present, so an agent cannot predict consequences.

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

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

Schema coverage is 100% and the project_id description already explains the session fallback, so the schema carries the parameter semantics. The tool description adds no parameter meaning, which meets the baseline 3 given high coverage and a single optional parameter.

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?

"Stop preview services" is essentially a restatement of the tool name and title, adding only the word "services". It does not differentiate from the sibling start_preview or explain what a preview environment is in this system.

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 statement of when to stop a preview versus when not to, and no mention of the counterpart start_preview or any prerequisites. An agent must infer the usage context entirely from the name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description is not required to establish that this is a destructive write. However, it adds nothing beyond that: no note on irreversibility, no mention of what happens to the key or whether the deletion cascades, and no error 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?

A single short, front-loaded sentence with no filler. It is efficient, though the brevity reflects under-specification rather than disciplined editing.

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

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

For an irreversible destructive tool with an undocumented required key and no output schema, the description leaves the agent without the essentials: what a key looks like, what happens on a missing key, and how this differs from the sibling delete tools.

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

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

Schema coverage is 50% and the required `key` parameter has no schema description at all; the description does not explain that `key` is the object path/identifier within storage, nor how it relates to project scoping. Only `project_id` is documented, and it is documented in the schema rather than the description.

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?

"Delete an object from app storage" names a verb and resource, so the basic act is understandable. But it is essentially a restatement of the title/name and gives no scope detail that would distinguish it from nearby file tools such as delete_file or storage_upload.

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

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

There is no indication of when to use this instead of delete_file, nor any prerequisite or caveat about when not to use it. The agent must infer the difference between 'app storage objects' and plain files entirely on its own.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the meaningful detail that the payload must be base64-encoded, but it stays silent on overwrite behavior when filename already exists, size limits, and permission 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?

A single short sentence with zero padding and the key concept (base64 upload) front-loaded. It is arguably too terse rather than bloated, but nothing in it is wasted.

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

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

For a 4-parameter write tool with no output schema and 25% schema coverage, the description leaves several call-critical questions unanswered: whether an upload overwrites an existing object, what content_type defaults to, and how project_id falls back to the session. Only the base64 encoding requirement is covered.

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

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

Schema coverage is only 25%, with project_id the sole documented parameter, so the description carries more of the burden than usual. Saying the object is base64 does clarify data_base64, and filename is self-evident, but content_type remains completely undocumented in both schema and description.

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

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

States a specific verb and resource: upload a base64 object to app storage. It is clear what the tool does, but it never distinguishes itself from the sibling upload_file, nor does it say this writes a raw base64 payload rather than a local file.

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

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

No guidance on when to use this instead of upload_file, which is the obvious competing sibling, and no mention of prerequisites such as enabling storage or selecting a project. The agent must infer the choice from the name alone.

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 disclose destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds little beyond that: it does not explain whether the deployment is removed, whether the live URL stops working, whether data is preserved, or what permissions are required.

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

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

A single four-word sentence with no filler, and the key action is front-loaded. Nothing in it is redundant.

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

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

For a destructive operation, annotations cover the risk category and the schema covers the sole parameter. However, the description does not describe the concrete effect of unpublishing, which is important context an agent may need before invoking a destructive tool.

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

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

Schema description coverage is 100%, and the schema itself documents project_id as optional with the session fallback to use_project. The description adds no further parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource: "Unpublish the live app." It is clear what the tool does and reads as the inverse of the sibling publish_app, though it does not explicitly name or contrast with that 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 phrase "live app" weakly implies this applies only to a currently published app, but there is no explicit when-to-use guidance, no prerequisites, and no mention of publish_app as the alternative for the opposite operation.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is known. The description adds nothing beyond that — it doesn't say whether other project fields are preserved, whether the rename is immediate or reversible, or what happens to existing references.

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 words with zero waste and the key information front-loaded, but the brevity is under-specification rather than efficiency for a two-parameter mutation 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?

The tool has no output schema and half the parameters are undocumented, so the description carries the burden of explaining a rename mutation. It does not cover the target project selection, the new-name semantics, or the result, leaving meaningful 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 coverage is only 50%: `name` has no description and `project_id` documents the use_project session fallback. "Rename" implies `name` is the new project name, which is a small value add, but the description never addresses project_id, the required/optional split, or the 1–60 character constraint.

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?

"Rename a project" states a specific verb (rename) and resource (project), which is clearer than the tool's generic name update_project. It implicitly distinguishes the tool from siblings like create_project, delete_project, and rename_file, though it never names an alternative.

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

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

There is no guidance on when to use this versus get_project/use_project/create_project, and no mention of prerequisites such as needing an active project or session. The agent must infer the context of use entirely.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description only needs to add operational detail. It adds the target directory and the base64 encoding requirement, but says nothing about overwrite behavior on name collision, size limits, or what happens if .attachments/ does not exist.

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 short sentence with the destination front-loaded and no filler. Its brevity is efficient, though it edges toward under-specification rather than optimal density.

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

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

For a mutating tool with no output schema, 33% parameter coverage, and no annotations describing side effects, the description should say what is returned (path/URL) and how collisions are handled. Neither is present, leaving real gaps for an agent that needs to reference the uploaded file afterwards.

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 33% (only project_id is documented in the schema), so the description carries extra burden. It does clarify that data_base64 must be base64-encoded and that the file lands in .attachments/, but 'name' is left completely unexplained (filename vs. path, extension handling).

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 plus the destination scope ('upload a base64 file into .attachments/'), which is more than a restatement of the name. It does not, however, distinguish itself from nearby siblings such as write_file, edit_file, or storage_upload, so an agent still has to infer which upload/write path to take.

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

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

There is no explicit when-to-use or when-not guidance and no mention of alternatives. The only implied rule is 'use this when you have base64 data', while the presence of write_file, edit_file, and storage_upload in the sibling list makes the routing decision genuinely ambiguous.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world mutation. The description adds genuinely non-obvious behavior with 'wake its sandbox', hinting at resource provisioning/latency, but omits idempotency, whether it replaces an existing binding, and failure modes for invalid IDs.

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 short sentence, front-loaded with the primary action and carrying the side effect in a trailing clause. 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 one-parameter session-state tool with annotations covering safety and no output schema, the essentials are present but the scope of 'active' (does it persist across calls? does it affect only this session?) and parameter sourcing are left unstated.

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% for the sole required parameter, and the description merely says 'a project' without clarifying whether project_id is an ID, slug, or name, or how to obtain it (e.g., via list_projects). With low coverage the description should compensate but does 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?

States a specific verb and resource ('Bind a project as active for this MCP session') plus a secondary effect ('wake its sandbox'), which separates it from read-only siblings like get_project or list_projects. It stops short of explicitly naming which sibling to use instead (e.g., create_project vs update_project).

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

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

Usage is only implied: an agent can infer this must be called before project-scoped operations, but there is no explicit when/when-not guidance, no mention of what happens if a different project is already active, and no named alternative.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the description's only added signal is that the external interaction is a DNS lookup rather than a registry mutation. It says nothing about what a failed verification means, whether the call is asynchronous, whether results are polled or returned inline, or what state changes on success.

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?

Six words, front-loaded and free of filler, so it is maximally concise. The terseness is also under-specification: no sentence earns extra weight because none of the operational context an agent needs 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 non-read-only, open-world operation with no output schema and a partially documented schema, the description is too thin. It lacks the prerequisites, the meaning of a success/failure result, and any indication of propagation or retry behavior that an agent would need to use 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 only 50%: project_id is documented in the schema (including the use_project session alternative) but domain_id is a bare string with no description. The description does not compensate by explaining that domain_id is the identifier of an already-added custom domain or where to obtain it (e.g., list_domains).

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 pairs a specific verb ("Verify") with a specific resource ("DNS for a custom domain"), which is enough for an agent to distinguish this from add_domain, remove_domain, list_domains or set_primary_domain among the siblings. It stops short of saying what verification produces, but the core action is unambiguous.

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

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

There is no guidance on when this should be invoked: no prerequisite that the domain must first exist via add_domain, no mention that DNS records must be configured and propagated, and no alternative or exclusion. The agent must infer the entire workflow from the sibling names.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds the genuinely useful allowlisted-hosts constraint, but says nothing about rate limits, whether fetched content is truncated or converted (HTML→text), or how failures surface.

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

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

A single front-loaded sentence with zero filler; the constraint and use case are packed in efficiently. It is arguably too terse, but nothing is wasted.

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

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

The tool is simple (one required param), but with no output schema the description should say what comes back (page text, markdown, size limits) and how allowlist rejections appear. Those gaps are meaningful for an agent deciding 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 50%: project_id is documented in the schema, while url has no description. The description partially compensates by stating the URL must be http(s), but never explains the project_id/billing-scope relationship or what happens if it is omitted.

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 (Fetch) and resource (http(s) URL) plus a scope constraint (allowlisted hosts) and an intended purpose (docs/research). This distinguishes it well enough from web_search, which is the obvious sibling, though the contrast is only implicit.

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

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

"for docs/research" hints at when to reach for this tool and the allowlist note warns of a failure mode, but there is no explicit when-not guidance and no named alternative (e.g., use web_search to discover URLs first).

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, openWorldHint=true and destructiveHint=false, so the safety and reach profile is covered structurally. The description's only addition — naming the Mythex/Tavily gateway — restates the open-world nature already declared and adds nothing about result quality, latency, rate limits, or truncation.

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?

It is a single front-loaded phrase with zero waste, which is good, but the brevity here is under-specification rather than economy. Nothing an agent needs is present to be concise about.

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 three parameters, one-third schema coverage, no output schema, and a sibling (web_fetch) competing for the same intent, the definition should do much more. It leaves the agent guessing about result format, result count behavior, and the project_id/session relationship hinted at in the schema.

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

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

Schema coverage is only 33%: query and project_id carry any meaning while max_results has no description anywhere. The description contributes nothing about any parameter — not the query syntax, not what project_id scopes, not the default for max_results — so it fails to compensate for the coverage gap.

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 phrase "Web search via Mythex gateway (Tavily)" names a specific verb and resource, so an agent knows it performs an internet search. However, it makes no attempt to distinguish this from the sibling web_fetch or from search_files/search_photos, and the parenthetical vendor reference is more implementation trivia than purpose.

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 at all on when to use this instead of web_fetch, which is the obvious alternative for retrieving a specific URL. No prerequisites, no mention of cost/rate implications of calling an external gateway, and no exclusions.

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