DreamAgent Cloud

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

Annotations only declare the write/open-world/safe-to-re-run profile; the description adds material context beyond them: that a live deployment is replaced, that a paid plan is required, that explicit user confirmation must precede the call, and that execution is asynchronous with a polling follow-up (dreamagent_get_project_status until 'ready').

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

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

Front-loaded with a 'WRITE ACTION' label, then organized into short labeled blocks (confirmation, async behavior). Every sentence carries actionable information with no filler.

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

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

For a two-parameter async deploy tool with an output schema already covering return values, the description covers the operation, prerequisites, safety protocol, and post-call polling loop. Nothing an agent needs to invoke and follow up correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the load; it fully explains the semantics of 'confirm' (only set true after user agreement), which the schema documents only as a boolean with default false. 'project_id' is left unexplained, but its meaning is unambiguous from the tool's purpose.

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

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

States a specific verb pair and resource with concrete effect: rebuilds the app from current source files and pushes the new version live. Clear enough to act on, though it does not differentiate from the similarly-named sibling dreamagent_commit_push, which also 'pushes' changes.

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

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

Explicitly names the trigger ('Use after finishing file edits (dreamagent_write_file)') and the sibling it follows, states the account prerequisite (Pro/paid only), and gives the confirmation protocol with the exact parameter value (confirm=true). Little is left to inference.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds real behavioral context beyond that: the commit becomes a restorable/revertible entry in session and version history, direct MCP edits are the intended source, and execution is gated on confirm=true after user agreement.

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

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

Front-loaded with the WRITE ACTION classification and the core commit/push definition, then tight sections for usage cases and the confirmation gate. Slightly verbose with caps and parentheticals, but every sentence carries operational value.

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

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

An output schema exists, so return values need no explanation. Given the mutation semantics and 100% schema coverage, the description supplies everything an agent needs: the write classification, the auto_commit grouping workflow, the retry case, and the mandatory confirmation gate.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, giving a baseline of 3. The description goes further by explaining the gating semantics of confirm ('call only with confirm=true after they agree') and the grouping intent behind auto_commit=false, which the schema alone does not convey.

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

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

States a specific compound verb+resource (commit ALL pending changes and push to the private GitHub repo) and frames it as a WRITE ACTION. It is clearly distinguishable from siblings like dreamagent_write_file and dreamagent_edit_file, which mutate files rather than finalize a version.

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

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

Explicitly enumerates when to use it: (a) grouping several MCP writes/deletes into one version via auto_commit=false, or (b) retrying a failed commit. It also states the exclusion — chat-driven edits commit automatically — so the agent knows when NOT to reach for this tool.

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

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

Goes well beyond the annotations: it discloses that hidden/credential files are rejected, that auto_commit defaults to committing and pushing into session and version history, and that deletions remain recoverable via git history. This also reconciles the seemingly odd destructiveHint=false on a delete tool by explaining recoverability.

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

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

Four short sentences, front-loaded with the WRITE ACTION label and confirmation requirement, with no filler. Bold-style section markers make the precondition and the side effects scannable.

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

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

An output schema exists, so return values need no explanation, and the description covers the dangerous-outcome cases (credential rejection, commit/push side effect, recoverability). Remaining gap is path/identifier semantics and failure behavior, which matters at 0% 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 0% across 4 parameters, so the description must carry the load. It explains the confirm flag and implies auto_commit's default behavior, but never clarifies file_path semantics (relative vs absolute, project root) or project_id, leaving two required parameters undocumented in both sources.

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

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

States a specific verb and resource — 'delete one source file from a DreamAgent project' — with the scope narrowed to a single file. This is clearly separable from sibling write tools like dreamagent_write_file and dreamagent_edit_file without reading their schemas.

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

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

Gives an explicit precondition workflow: identify the file to the user and only call with confirm=true after agreement. It does not, however, name an alternative tool or say when deletion is preferable to editing/archiving, so the routing guidance is one-sided.

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, and the description adds meaningful behavioral context: it is a WRITE ACTION, it mutates the frontend, and it requires confirm=true before execution. It stops short of disclosing what happens to existing UI/pages that the redesign replaces, which would be valuable given the mutating nature.

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

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

Front-loads 'WRITE ACTION' so the operation type is immediately visible, then scopes the resource and lays out the workflow and confirmation steps in a scannable structure. Every sentence carries actionable information with no filler.

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

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

An output schema exists, so return values need not be explained. The description covers the operation type, scope, workflow, and confirmation gate, giving an agent everything needed to invoke it correctly for this multi-parameter, open-world write tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining the confirm workflow (show project + instructions, then call with confirm=true) and reinforcing that the image itself is the spec. This meaningfully clarifies how to set confirm and how to treat image_base64 vs instructions beyond the schema text.

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

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

States a specific verb (redesign) and resource (a website project's UI/frontend) with a clear scope constraint ('Website projects only'). It clearly distinguishes itself from file-editing siblings like dreamagent_edit_file and dreamagent_write_file by centering on image-driven UI redesign.

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

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

Gives a clear workflow context (user supplies image + instructions, agent generates and base64-encodes it) and an explicit scope exclusion ('Website projects only'), plus a mandatory confirm-before-calling procedure. It does not, however, explicitly compare itself to alternative tools an agent might reach for, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: it discloses atomic all-or-nothing validation ('if any find fails to match, the file is left untouched'), the exact-match whitespace requirement, the confirm=true gate, and the auto_commit batching guidance. The destructiveHint=false annotation is consistent with the described non-corrupting, validated 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?

Front-loaded with a capitalized action label, then segmented into clear paragraphs for behavior, prerequisites, and confirmation. Despite its length, every sentence carries operational information (cost/safety rationale, validation semantics, confirm gate); 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 write tool with an output schema present, the description covers what it need not (return format) and what it must: atomicity, exact-match requirements, confirmation, and the batching interaction with dreamagent_commit_push. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so baseline is 3, but the description meaningfully augments the critical 'edits' parameter by stressing that 'find' text must be copied EXACTLY including whitespace and indentation, and explains the confirm/auto_commit workflow implications. This adds real operational meaning beyond the schema text.

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

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

States a specific verb (exact search/replace edits), resource (existing file in a DreamAgent project) and scope (small, targeted changes). It explicitly distinguishes itself from dreamagent_write_file, so an agent can route correctly without opening either schema.

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

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

Gives an explicit preference rule (PREFERRED over dreamagent_write_file for editing), names the exclusion (use write_file only to CREATE or fully rewrite), and prescribes a prerequisite (read the file first) plus a confirmation workflow. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation context: it is free (no cost), and it defines what the diff is measured against (the last commit, not live state).

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 operation and its scope before the usage hint, with no filler. 'Read-only' mildly duplicates the readOnlyHint annotation, which is the only wasted fragment.

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

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

An output schema exists, so return values need no explanation, and the annotations cover safety. For a two-parameter read tool the description is nearly sufficient; only the parameter formatting/identifier semantics remain unaddressed.

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

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

Schema description coverage is 0%, so the description bears the full burden for both parameters. 'One project file' implicitly maps to project_id and file_path, but neither parameter's expected format (integer project id, repo-relative vs absolute path) is clarified anywhere.

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 ('Git diff of one project file against the last commit') with explicit scope, distinguishing it from read_file and list_commits by naming what is compared (working tree vs last commit). The parenthetical 'pending (not yet live) changes' further disambiguates the output from a file listing.

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 after edits to review exactly what changed before rebuilding' gives a clear triggering context and a natural workflow position (post-edit, pre-build/publish). It does not name alternative tools such as read_file or list_commits, so it stops short of explicit when-not/alternative 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real value beyond them: it discloses ordering (newest first), the source ('persistent commit log'), and the contents of each entry. It stops short of describing pagination or what happens when limit exceeds available commits.

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

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

Two sentences, front-loaded with the identity of the resource and its returned fields, with the usage/UX hint placed second. The parenthetical field list and dashboard instruction both earn their space, though the second sentence is slightly long.

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

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

An output schema exists, so return values need not be spelled out, and the description is still self-sufficient for a read-only list tool. The only real omission is any guidance on the limit parameter, which neither the description nor the schema covers.

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

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

Schema description coverage is 0% and there are 2 parameters. The description implies a bounded list ('recent commits') but never explains the limit parameter, its default of 10, or whether project_id is required/its format — so the schema-side gap is not compensated.

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 (commits/version history) and enumerates the returned fields (hash, message, status, timestamp) plus ordering (newest first). It is clearly distinguishable from siblings like dreamagent_commit_push or dreamagent_get_file_diff without opening a schema.

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

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

Gives an explicit purpose ('use it to review what changed and when') and a concrete downstream workflow (tell the user the short hash so they can restore from the dashboard UI). It does not state when not to use it or name an alternative listing tool, but no close alternative exists among the 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 and destructiveHint=false, so safety is covered. The description adds the non-obvious behavioral detail that hidden files such as .env are omitted, which matters for discovery. No rate limits or pagination context, but those are minor for a tree listing.

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

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

Two sentences, front-loaded with purpose and followed by usage guidance. The parenthetical scope caveat is integrated without waste; nothing needs trimming.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. For a simple one-parameter read tool the description is nearly sufficient, with only the undocumented project_id as a residual hole.

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 single required parameter project_id, so the description carries the burden and fails to explain it at all — no format, no source, no hint about where to obtain the ID. This is the definition's clearest 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 specific verb ('List') and resource ('file tree of a DreamAgent project') plus a precise scope qualifier: source files only, hidden files like .env excluded. An agent can distinguish it from siblings such as list_project_env or read_file without opening any schema.

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

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

Explicitly tells the agent when to use it: 'Use before reading or editing a file to find the correct path,' which positions it ahead of read_file/edit_file. It doesn't name an alternative or state exclusions, but the sequencing guidance is concrete.

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 genuinely new context beyond the annotations: 'no credits consumed' (a cost trait not expressible in annotations) and that enabled tools are usable from ANY project via dreamagent_chat. It does not cover rate limits or output shape, but with an output schema present that is acceptable.

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

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

Front-loads the identity and payload in sentence one, then usage in sentence two. The parenthetical tool enumeration is long but earns its place by telling the agent what 'superpowers' concretely means. Slightly wordy overall, but no sentence is filler.

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

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

With an output schema present, return values need not be described, and the description still previews the key returned fields (enabled state, beta pricing). It covers what the tool is, when to call it, and what to do next, which is everything an agent needs for a zero-param list tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a 0-param tool is 4. The description correctly implies no filtering or scoping input is required.

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 (DreamAgent Superpowers) and immediately enumerates what those are — song/video/image generation, voiceover, lip sync, voice clone, transcription, media processing, PDF tools — plus the returned fields (enabled state, beta pricing). This is clearly distinguishable from siblings like dreamagent_list_projects or dreamagent_list_global_integrations.

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 three explicit triggering conditions (what tools are available, whether a specific tool is enabled, what can be added to a project) and routes the agent onward to dreamagent_chat for actual invocation. It does not state any when-not condition or prerequisite, but the context is unambiguous.

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

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

Annotations already declare the safe read profile (readOnlyHint, destructiveHint false), so the bar is lower, yet the description adds real constraints the annotations do not: .env/hidden files and binaries are not readable. It stops short of noting size or truncation behavior for large files.

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 purpose, then path semantics, then the readability caveat. Every sentence adds information 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?

An output schema exists, so return values need not be described. The description covers purpose, path origin/format, and readability limits, which is sufficient to invoke correctly; only the untouched project_id and large-file behavior leave minor gaps.

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

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

Schema coverage is 0%, so the description carries the burden and does well for file_path: it defines it as a project-relative path sourced from dreamagent_list_files and gives two concrete examples. project_id is left to inference, but its meaning is unambiguous next to file_path.

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 ('Read a source file from a DreamAgent project') and scopes it with a restriction on what is readable (hidden files, binaries). It does not explicitly contrast with read-adjacent siblings like dreamagent_get_file_diff, so sibling differentiation 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?

It implies context by pointing to dreamagent_list_files as the source of the path, which tells the agent where the value comes from, but it never states when to use this tool versus alternatives such as get_file_diff or edit_file.

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

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

Annotations declare the safety profile (readOnly, non-destructive, closed-world), and the description adds substantive behavior beyond them: the return is a PNG image content block plus a public URL, the URL allow-list is enforced both locally and by a host firewall, and private/internal hosts are rejected. That is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the scope constraint and organized into short, purposeful blocks with no filler. There is mild redundancy between the 'Non-DreamAgent URLs are rejected' line and the closing 'private/internal hosts are rejected' sentence, which keeps it from a perfect score.

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

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

With no output schema, the description compensates by explaining what is returned (PNG image block plus public URL). Scope, required input, and rejection behavior are all covered, so an agent has everything needed 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 description coverage is 100%, so all three parameters (url, width, height) are already documented with types, defaults and ranges. The description only reinforces the url requirement ('No project id needed — just the URL'), adding no new meaning for width/height, 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?

The description states a precise verb (capture a screenshot) and a tightly scoped resource (a DreamAgent-hosted page by URL), opening with 'WEBSITE PROJECTS ONLY' so the agent can immediately distinguish it from sibling tools that touch source files or project metadata.

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

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

It gives clear context for use ('Best for checking a project's live pages after edits or deploys and reviewing layouts') and clear exclusion rules ('Non-DreamAgent URLs are rejected'). It never names an alternative sibling (e.g. read_file for source inspection), so it stops short of full when/when-not/alternative coverage.

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

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

Goes well beyond the annotations: discloses that the write is auto-committed and pushed to GitHub, recorded in session and version history, only live after dreamagent_build_publish, and enumerates server-side guards (path confinement, .env/.git/key rejection, malware scanning, 2MB cap) plus the reversibility path via version history. Annotations only cover readOnly/destructive/openWorld, so this description carries real extra context.

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

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

Front-loads the core action and uses CAPS-labelled sections (CONFIRM, MULTI-FILE EDITS, GUARDS) that make scanning easy. It is longer than strictly necessary — the guards paragraph and undo guidance overlap somewhat — but every section carries actionable 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 mutation tool with an output schema, no annotation contradiction, and 0% schema coverage, the description supplies the workflow ordering, safety constraints, confirmation requirement, and side effects an agent needs. Return-value details are correctly omitted since an output schema exists.

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

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

Schema description coverage is 0%, so the description must compensate. It explains auto_commit's dual role and the batch workflow, and contextualizes content ('exact content given') and path, but never explicitly defines the 'confirm' boolean or the project_id integer, leaving two of five parameters to inference from prose.

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+scope: 'overwrite or create one source file in a DreamAgent project with the exact content given.' It also explicitly names the sibling it is not (dreamagent_edit_file) and the distinction (whole-file vs targeted find/replace).

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

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

Gives explicit when-to-use and when-not-to-use routing: prefer dreamagent_edit_file for changing an existing file, and pass auto_commit=false plus a single dreamagent_commit_push for multi-file edits. It also imposes a confirmation protocol ('never write on the first mention') — no inference required.

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