DreamAgent

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 already declare destructiveHint=true, so the safety profile is covered, but the description goes further: it names the possible backend responses ('Query cancelled', 'Cancellation requested' for durable runs, 'No active query found') and prescribes the post-call workflow of polling until run_status reports 'cancelled'. That is meaningful behavioral context beyond the structured fields.

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 destructive warning is front-loaded in caps, followed by usage constraint, then return values, then follow-up steps. Every sentence carries operational value; 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 destructive action with full annotation and schema coverage, the description supplies everything an agent needs: the trigger condition, the possible outcomes, and the required next step. Nothing material is missing.

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

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

Schema description coverage is 100% for the single session_key parameter, so the schema carries the semantic load. The description adds no format, source, or retrieval guidance for session_key beyond what the schema states, which is the baseline case.

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 up front ('stops an AI edit that is currently running') and scopes it to a single running operation. An agent can distinguish it from siblings like dreamagent_get_chat_status or dreamagent_chat 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?

Explicit when-to-use ('Use ONLY when the user explicitly asks to stop/cancel the active edit') and explicit when-not-to-say ('do NOT claim the requested change was completed'). It also names the follow-up tools (dreamagent_get_chat_status / dreamagent_get_edit_progress) and the target state to poll for.

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

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

Annotations only cover the safety profile (not read-only, non-destructive, open-world); the description adds substantial context beyond that: asynchronous return with session_key, automatic code/test/rebuild/commit behavior, AI-credit consumption, a one-edit-at-a-time concurrency rule, and concrete error semantics (HTTP 402/409/423/404/401 and 'ERROR:' prefixes).

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?

Lengthy, but every block is labeled and front-loaded (WRITE ACTION, ASYNCHRONOUS, ERRORS, ONE EDIT AT A TIME, SUPERPOWERS), so an agent can scan for the relevant rule. Slightly verbose, with a few restatements (e.g., the failure/terminal-state caveat appears twice), keeping it short of a 5.

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

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

For an async mutation tool with an output schema, the description covers everything an agent needs before and after calling: how to invoke, that it returns immediately, which tools to poll, when success can be reported, credit impact, and the concurrency and error envelope. No material gap remains.

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, but the description adds real meaning on top: it instructs that the message should describe ONLY the desired change and that the agent handles the rest, and it ties session_key/new_session to session continuation vs. fresh topics. It does not add format constraints beyond that.

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

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

Opens with 'WRITE ACTION — builds, modifies, or fixes an EXISTING project with a natural-language instruction', giving a specific verb class, resource, and scope. It explicitly separates itself from read/advice tools, so an agent can distinguish it from siblings like dreamagent_get_project_status or dreamagent_edit_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?

Gives explicit when-to-use ('add X', 'fix Y') and when-not ('advice, analysis, review, or suggestions' → do NOT call). Also routes to siblings by name for monitoring (dreamagent_get_edit_progress, dreamagent_get_chat_status) and catalog lookup (dreamagent_list_superpowers).

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?

Annotations only say writable, non-destructive, open-world. The description adds what they cannot: creation is asynchronous with bot/website-specific durations, credentials are stored as project secrets and never echoed back, raw tokens are rejected, and the 'three.js' keyword triggers a platform stack install. These are non-obvious behaviors an agent would otherwise get wrong.

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

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

Well front-loaded with WRITE ACTION / CONFIRM BEFORE CALLING, but it runs long and carries prompt-level content (full per-type outline templates, a stale-tool-list troubleshooting aside) that inflates every invocation. The signal is good; the volume is excessive for a tool description.

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?

Output schema exists, so return values need no explanation. Everything an agent needs to invoke correctly — confirmation, credential sourcing, description content rules, async polling, per-type constraints — is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further: it conditions bot_token_integration_id on bot project types, explains global_integration_ids as saved-key imports, and specifies what the `description` parameter should contain (vision, audience, UX, tone) and what it must not contain (stack, CI/CD, auth). That is meaning beyond the schema's one-line field blurbs.

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

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

Opens with a precise verb+resource and enumerates the resource variants (website, Telegram bot, Discord bot, AI agent). It explicitly excludes the close-but-different case ('not for questions about what to build'), which separates it from sibling dreamagent_chat.

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 when-to-use gate, a mandatory confirm-first protocol with ordered steps, and names the prerequisite tools (dreamagent_list_global_integrations, dreamagent_list_superpowers) and the follow-up tool (dreamagent_get_project_status). An agent knows exactly what to do before, during, and after.

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 (not read-only, not destructive, closed-world). The description adds real value beyond that: a new session does not replace or affect the existing project and earlier sessions stay available — exactly the non-obvious, side-effect context an agent needs. It doesn't mention auth or rate limits, but those are minor here.

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

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

Three sentences, front-loaded with the verb and resource, then the usage trigger, then the non-impact guarantee. No wasted words; slightly padded by the dash clause, but each sentence earns its place.

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

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

An output schema exists so return values needn't be described, and the annotations carry safety. Combined with the non-replacement guarantee, an agent has enough to call this correctly. Missing only explicit alternatives to route against sibling session 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 100%, so both params (label, project_id) are fully documented in the schema. The description adds only that the session belongs to a project, which is largely redundant. Baseline 3 when the 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?

Specific verb (create) plus resource (development session for a project) and clarifies it is a separate conversation with its own context. That scope statement distinguishes it from dreamagent_chat and dreamagent_list_sessions 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 a clear triggering condition ('when the user wants to start a distinct development topic') but does not name the alternative tools — e.g. chat vs create_session or list_sessions — so an agent must infer the boundary itself.

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 only declare read-only/non-destructive/non-open-world; the description adds substantial behavioral context beyond that — the polling contract, the 'next_after' cursor reuse, what each terminal state means, the HTTP 402 rejection case, and that a stream error does not imply the server-side run stopped. That is exactly the extra context the annotations do not 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 purpose and usage, then the return/terminal-state detail. Dense and every sentence carries information, though the enumerated return-field breakdown is somewhat long and partially overlaps the declared output schema.

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

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

For an async polling tool with 8 possible run_status values and three distinct terminal outcomes, the description covers the full state machine, error handling, and recovery path. Since an output schema exists, the return-value detail is a bonus rather than a necessity, and nothing an agent needs to poll correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds real meaning: session_key's provenance and non-secret nature, and the semantics of the 'after' cursor (taken from 'next_after' on the previous check, 0 on the first). It goes modestly beyond the schema text rather than merely restating it.

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

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

States a specific verb and resource ('check the progress and final status of a specific AI development session using its session key') and names the sibling it must not be confused with (dreamagent_get_edit_progress) plus where the key originates (dreamagent_chat / dreamagent_list_sessions). An agent can distinguish this from cancel_chat, chat, and get_edit_progress 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?

Gives explicit when-to-use ('monitor an asynchronous edit until it completes, fails, or is cancelled — keep checking until a terminal state') and routes to the alternative for the ambiguous stream-error case ('verify with dreamagent_get_edit_progress'). It also clarifies the session key is an identifier, not a secret, removing a likely agent hesitation.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false and the description is fully consistent with them, while adding substantial context annotations cannot carry: the return field layout, terminal outcomes (finished / NOT started with reason / stream error / no active run), the full run_status enum, and the HTTP 402 insufficient-credits failure mode.

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 purpose and usage before the return-value detail, and every sentence carries information. The run_status enum listing is dense but operationally useful; the block is longer than minimal but has 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?

Despite an output schema existing, the description documents the actual returned fields and terminal result lines, plus the failure case. For a read-only progress probe with one param, nothing an agent needs to call or interpret it 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% for the single project_id param, so baseline is 3. The description goes further by explaining the semantics — 'no session key needed: the project id retrieves the session holding the latest edit' — which tells the agent why one id is sufficient and where the session key comes from.

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 ('check the latest AI edit progress for a project') and immediately distinguishes itself from siblings by naming dreamagent_get_project_status and dreamagent_get_chat_status with their respective scopes. An agent can route correctly 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 states when to use (edit finished? session key unavailable? before starting a new edit) and when NOT to act ('If edit_active is true, do NOT launch another edit for the same project'). Alternative tools are named with their differing semantics.

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 declare readOnly/ non-destructive safety. The description adds real behavioral context beyond that: the terminal vs progressive state model ('creating', 'building', 'deploying', 'ai_provisioning') and the instruction to treat any non-terminal status as still building. It does not discuss polling frequency or rate limits, so 4 rather than 5.

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 purpose, then state semantics, then the routing note. Every sentence carries information and there is no 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?

With an output schema present, the description need not enumerate return fields, and it supplies the state interpretation and the sibling disambiguation an agent needs. Nothing required to call 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?

Only one parameter (project_id) and schema coverage is 100%, so the schema already documents it fully. The description adds no format or identifier guidance beyond the schema; 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 (check) and resource (project's creation/deployment state) and explicitly differentiates from the sibling dreamagent_get_edit_progress. An agent can tell it apart from get_edit_progress and list_projects 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 explicit when-to-use: after dreamagent_create_project, polling until ready or failed, and when the user asks whether a project is ready/live. It also names the alternative for edit progress, so no inference is required.

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 cover the safety profile (readOnly, non-destructive), yet the description adds real behavioral context: secret values are never returned and only IDs/metadata (type, key name, verified, title) come back, plus the exact ID field names used downstream. That is information an agent cannot infer from 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?

Front-loaded with the imperative usage rule and organized into purpose, ID-reference semantics, and fallback guidance. It is longer than strictly minimal, but each block (secret handling, fallback instructions) carries actionable content for the next call.

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-format detail is not required, and the description still summarizes the useful returned fields. Combined with the when-to-use rule and the fallback path, an agent has everything needed to invoke it and act on the result.

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 the rules give a baseline of 4 — there is nothing for the description to disambiguate. The schema is empty, so no coverage gap exists to compensate for.

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 — listing the user's saved credentials (Global Integrations) — and is immediately distinguishable from siblings like dreamagent_list_projects or dreamagent_list_files. The parenthetical alias also clarifies the domain terminology an agent will encounter elsewhere.

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 imperative trigger ('ALWAYS call this before creating any bot project or asking the user for a token/API key') and a fallback path when nothing suitable is saved. It also names the alternatives implicitly by steering the agent away from asking for pasted secrets.

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 non-destructive, so safety is covered. The description adds meaningful beyond-annotation context: values are masked and secrets are never returned, which tells the agent what it will and won't see. It doesn't discuss pagination or limits, but the masking disclosure is a substantive behavioral trait not captured 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?

Front-loads the core action and the masking caveat, then closes with the sibling distinction. Each sentence earns its place, though the quoted example question is slightly verbose and could be trimmed without losing meaning.

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 read-only listing tool with full schema coverage, annotations, and an output schema present, the description covers what it returns, what it masks, and how it differs from the global-integrations sibling. Nothing an agent needs to call 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 description coverage is 100% and there is a single required integer project_id with its own description. The description doesn't add syntax or meaning beyond 'a project's environment variables', which is expected given the schema already documents the parameter fully. 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 (project environment variables) and enumerates the returned fields (name, title, description, docs URL, category). It explicitly distinguishes itself from the sibling dreamagent_list_global_integrations, 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 concrete when-to-use conditions: 'to see which integrations a project already has before adding more, or to answer "what keys does my project have?"'. It also names the alternative (global integrations) and the distinction between project-specific vars and global ones, so the selection decision 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the name-to-ID resolution workflow but says nothing about result size, pagination, ordering, or whether all projects are returned regardless of status — gaps that matter for a list endpoint.

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, front-loaded with purpose before usage. The enumeration of returned fields is mildly redundant given an output schema exists, but it costs little and reads cleanly.

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 covering return shape and annotations covering the safety profile, the description supplies the remaining missing piece — the ordering rule relative to mutation tools. Nothing an agent needs in order to call this correctly is 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 description coverage is 100%, and the schema itself carries the important caveat that filtering by 'creating' does not match every in-progress project. The description adds no parameter-level information, 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 (DreamAgent projects) plus the exact fields returned (name, ID, type, status, live domain). This is clearly distinguishable from single-project siblings like dreamagent_get_project_status or dreamagent_list_files.

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

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

Gives explicit trigger conditions ('see, find, select, or check their projects') and a hard workflow rule: always call before modifying a project when the ID is unknown, resolving names to IDs here first. This is the kind of prerequisite ordering an agent cannot infer from the schema.

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 non-obvious context beyond that: the returned key is an address/reference for a session and explicitly not an auth credential or secret, which preempts a plausible agent misread. It stops short of describing ordering, pagination, or result limits.

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 purpose in the first clause, then the return contents, then downstream routing. Three sentences with little waste, though the credential-disclaimer sentence is slightly tangential to the listing action itself.

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, read-only listing tool with an output schema and full annotation coverage, this is complete: purpose, returned identifier, and the two follow-on tools that consume it are all stated. Nothing an agent needs to select or 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 description coverage is 100% (one required project_id), so the baseline is 3. The description only implies project scoping via 'a project's development sessions' and adds no format, type, or lookup detail beyond the schema's own 'the project.' entry.

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 a project's development sessions (conversation threads)') and immediately clarifies what each result contains (session identifier/key and context). An agent can distinguish this from dreamagent_list_projects or dreamagent_create_session 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?

Explicitly routes the agent downstream: pass the session key to dreamagent_chat to continue a thread, or dreamagent_get_chat_status to monitor it. That is concrete when-to-use guidance naming real siblings, though it does not address when to call this versus other listing tools (e.g. list_projects) or whether listing is scoped/limited.

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 already declare a non-readonly, non-destructive, closed-world operation, and the description does not contradict that. Beyond the annotations it usefully discloses that lock state is not machine-readable from this tool and prescribes a staleness-check workflow, which is real behavioral context. It stops short of describing what happens on release (e.g. effect on other sessions, failure modes), keeping it at a 4.

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 RECOVERY-ONLY framing is front-loaded in the first clause, followed by the exclusion and the diagnostic steps. Every sentence carries distinct information (scope, prohibition, detection method, user-confirmation caution) 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?

With an output schema present, return values need no explanation, and the description covers purpose, gating condition, detection workflow, and the human-confirmation requirement. For a single-parameter recovery tool, nothing an agent needs to call 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?

Only one parameter, and schema description coverage is 100%, so the schema already documents project_id fully. The description adds no format, constraint, or sourcing detail beyond it; per the rubric this is the baseline 3.

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

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

States a specific verb and resource ('releases a project's editing lock') plus the exact scope condition ('stale or abandoned session blocks new modifications'). It explicitly distinguishes itself from the normal editing path, so an agent can separate it from siblings like dreamagent_edit_file or dreamagent_chat.

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 ('RECOVERY-ONLY'), when-not-to-use ('NOT a normal editing step, and NEVER a way to bypass an actively running edit'), and a concrete diagnostic procedure using dreamagent_get_edit_progress and dreamagent_chat to determine staleness. It even adds a procedural caution ('Confirm with the user before releasing'), leaving nothing to inference.

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

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

Annotations 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.