DreamAgent

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

Annotations already indicate destructiveHint=true, and the description reinforces this with 'DESTRUCTIVE —' and adds critical context: do not claim completion, report that it was stopped. It also discloses return value variations and the need to poll for final status.

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

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

The description is compact yet packed with necessary information: warning, usage restriction, post-action behavior, return examples, and follow-up steps. Each sentence serves a purpose, though the density is slightly high.

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

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

For a one-parameter destructive tool with a clear output schema, the description covers purpose, when to use, behavior after cancellation, possible return values, and follow-up polling. It is fully sufficient for an agent to invoke and handle the tool correctly.

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

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

Schema covers session_key with 100% description coverage, so the baseline is 3. The description only refers to 'the running edit' without adding new parameter-level semantics beyond what the schema already provides.

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

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

The description clearly states 'stops an AI edit that is currently running' with a specific verb and resource. It differentiates from sibling status-polling tools by focusing on cancellation, making it unambiguous.

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

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

Explicitly states 'Use ONLY when the user explicitly asks to stop/cancel the active edit' and provides post-cancellation instructions, including naming sibling tools for polling (dreamagent_get_chat_status / dreamagent_get_edit_progress).

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?

Discloses asynchronous behavior, immediate return with session_key, need to monitor until terminal state, AI credit consumption, error format with specific HTTP codes, and one-edit-at-a-time rule. Adds substantial context beyond the annotations.

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

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

The description is long but well-structured with clear paragraphs for purpose, usage, async behavior, errors, and concurrency. Each section earns its place given the tool's complexity, though it could be slightly trimmed without losing value.

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

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

For a complex asynchronous tool with multiple error codes and concurrency constraints, the description fully covers operational nuances, monitoring requirements, and failure interpretation. No gaps identified.

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

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

Schema covers all 4 parameters with descriptions (100% coverage), so the baseline is 3. The description adds high-level guidance about message content ('Describe ONLY the desired change') but does not significantly expand parameter-level semantics.

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

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

The description clearly states it is a WRITE ACTION that builds, modifies, or fixes an EXISTING project via natural-language instruction. It differentiates from siblings by explicitly excluding advice/review requests and directing to status tools for monitoring.

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

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

It provides explicit when-to-use criteria ('only when the user clearly asks for a change') and when-not-to-use ('advice, analysis, review... do NOT call this'), and names alternative tools (dreamagent_get_edit_progress, dreamagent_get_chat_status). Concurrency guidance is also given.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals critical behavioral traits: creation is asynchronous, raw bot tokens are never accepted, credentials are stored as secrets and never exposed, and it 'never create[s] on the first mention.' This gives the agent a complete safety and workflow model with no contradictions.

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

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

The description is long, but the complexity justifies it: 6 parameters, 4 project types, and critical safeguards. It is well-structured with bold section headers, bullet lists for each project type, and front-loaded key warnings like 'WRITE ACTION' and 'CONFIRM BEFORE CALLING.' Every section carries necessary information without redundancy.

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

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

Given the output schema exists and the tool's complexity, the description covers all operational context: pre-call credential discovery, confirmation steps, asynchronous behavior with status polling, default-inference guidance, and per-type description templates. The agent has everything needed to invoke the tool correctly without guessing.

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

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

Although the schema already covers 100% of parameters, the description adds deep semantics: bot_token_integration_id is REQUIRED for Telegram/Discord bots and must come from dreamagent_list_global_integrations, description is a creative brief with explicit inclusions/exclusions, and global_integration_ids imports saved keys. It transforms bare parameter names into actionable guidance.

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

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

The description opens with 'WRITE ACTION — creates a new DreamAgent project' and enumerates the four project types, giving a specific verb, resource, and scope. It also distinguishes itself from siblings by explicitly stating 'not for questions about what to build' and later referencing dreamagent_get_project_status for the asynchronous follow-up.

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

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

Provides explicit when-to-use: 'Use ONLY when the user clearly asks to create/build a new project; not for questions about what to build.' It goes further with a mandatory confirmation protocol, steps to list/choose integrations, and the instruction to poll dreamagent_get_project_status after calling, making alternatives and sequencing unmistakable.

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

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

The description adds valuable context beyond the annotations: 'A new session does NOT replace or affect the existing project — earlier sessions remain available.' It clarifies the operation is non-destructive and that sessions are isolated but persistent. Annotations already indicate destructiveHint=false, but the description enriches this with specifics about project impact and session persistence. A 4 is warranted because it doesn't mention whether a project must already exist or what the new session's active status is.

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

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

The description is two sentences: the first states the core purpose, the second provides usage and a behavioral caveat. Every sentence earns its place, with no redundant information or filler. It is appropriately front-loaded and easily scannable.

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

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

For a tool with two parameters and an output schema, the description is fairly complete. It covers purpose, usage, and a key behavioral guarantee. However, it doesn't explicitly state that project_id must reference an existing project (though implied by sibling create_project), nor does it mention the return value—though the output schema presumably covers that. Slightly more detail could push it to 5, but 4 is a solid score.

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%, with both 'project_id' and 'label' already described in the input schema. The tool description adds only minimal meaning beyond this, such as implying project_id refers to an existing project. The baseline of 3 is appropriate because the schema does the heavy lifting and the description doesn't compensate with additional parameter context.

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

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

The description clearly states the tool's function: 'Create a new development session for a project — a separate conversation with its own context.' It uses a specific verb (create) and resource (development session), and distinguishes itself from sibling tools like create_project (creating a project) and chat (continuing a conversation). The phrase 'separate conversation' further clarifies its scope.

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

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

The description provides an explicit when-to-use trigger: 'Use when the user wants to start a distinct development topic.' It also implies a contrast with existing sessions by stating earlier sessions remain available. However, it doesn't explicitly name alternative tools (e.g., 'use dreamagent_chat for continuing a conversation'), so it's clear but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond this: exact return fields ('active=', 'run_status=', 'next_after='), terminal states including early rejection reasons like HTTP 402, the meaning of stream error, and the full run_status enumeration. It also clarifies the session key is 'an identifier, not a secret,' which is non-obvious behavioral information.

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

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

The description is longer than the calibration high example but stays dense and informative. It front-loads the core purpose, then organizes return values and run_statuses in a structured way. Every sentence contributes needed behavioral detail, though a slight trim could improve scannability without losing 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?

Given the tool's complexity (polling logic, multiple terminal states, error conditions, and cursor handling), the description is remarkably complete. It explains the fields returned, the meaning of each run_status, how to handle stream errors, and what 'done=true' lines indicate. Even with an output schema present, this description fully equips an agent to use the tool correctly in a polling loop.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds value by stating the session key comes 'from dreamagent_chat or dreamagent_list_sessions' and reinforcing the `after` parameter as a cursor from the previous check. This elevates it above the baseline 3 but does not add entirely new syntax or format details beyond the schema.

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

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

The description clearly states the tool checks 'the progress and final status of a specific AI development session using its session key,' with a specific verb and resource. It distinguishes itself from siblings by explicitly positioning this as the tool for monitoring an asynchronous edit until terminal state, contrasting with dreamagent_get_edit_progress for verification after stream errors.

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

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

The description gives explicit when-to-use guidance: 'Use this to monitor an asynchronous edit until it completes, fails, or is cancelled — keep checking until a terminal state.' It also names an alternative tool (dreamagent_get_edit_progress) for the stream error case and states the session key source, providing clear context for when to invoke this tool versus siblings.

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

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

Beyond the readOnlyHint annotation, the description explains that no session key is needed, how the project id maps to the latest session, details the return fields (session_key, edit_active, run_status, chunks, result), and enumerates run_status values and possible result outcomes. This is rich behavioral 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?

The description is well-structured: purpose first, then usage, return fields, status enum, sibling differentiation, and a caution. Every sentence contributes valuable information without redundancy, making it dense but not verbose.

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

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

With one parameter and an output schema, the description covers purpose, usage context, full return format, run_status values, and an operational constraint. This provides enough information for an agent to select and invoke the tool correctly without confusion.

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

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

The schema only describes project_id as 'the project being edited.' The description adds crucial meaning: 'the project id retrieves the session holding the latest edit' and explicitly notes 'no session key needed,' which substantially clarifies how the parameter is used.

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

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

The description clearly states 'Check the latest AI edit progress for a project using its project identifier' — a specific verb and resource. It also distinguishes itself from dreamagent_get_project_status and dreamagent_get_chat_status, making the tool's unique scope unambiguous.

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

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

Explicitly provides when to use: 'Use when the user asks whether their edit is finished, when the session key isn't available... and BEFORE starting any new edit.' It also contrasts sibling tools and warns against launching another edit when edit_active is true, giving clear guidance on alternative selection.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description explains terminal states ('ready', 'failed'), progressive phases ('creating', 'building', 'deploying', 'ai_provisioning'), and instructs treating non-terminal states as still building. This adds meaningful interpretative 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?

The description is well-structured with a clear first sentence, followed by state details and usage guidance. The NOTE is valuable and not redundant. Every sentence earns its place with no fluff.

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

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

Given the tool's simplicity (one param, output schema present, annotations provided), the description fully covers purpose, usage, state interpretation, and exclusions. No critical gaps remain.

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% because project_id has a description ('the project to check'). The tool description adds no extra semantic value about the parameter, so baseline 3 is appropriate.

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

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

The description clearly states the tool checks a project's creation/deployment state, with a specific verb and resource. It explicitly distinguishes from sibling tools by noting it reports build/deploy state, not AI edit progress, and names the alternative tool for edits.

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: after dreamagent_create_project (poll until ready or failed) and whenever the user asks if a project is ready or live. It also gives an exclusion by directing edit-progress queries to dreamagent_get_edit_progress.

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

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

The description adds valuable behavioral context beyond the annotations: it discloses that secret values are never returned, only IDs and metadata (type, key name, verified, title). It also explains how these IDs are used in project creation. No contradiction with the read-only annotation; instead, it reinforces the safe, non-destructive nature of the tool.

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

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

The description is succinct and well-structured, with the purpose stated first and subsequent paragraphs adding usage guidance and fallback instructions. Every sentence contributes meaning without redundancy or unnecessary length.

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

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

For a simple, parameterless read-only tool, the description is thorough: it explains what the tool does, when to call it, what to expect in the response (IDs and metadata), and how to handle cases where no suitable integration is saved. The presence of an output schema reduces the need to detail return values, and the description covers all necessary workflow context.

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

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

The tool has no parameters, and the description appropriately does not invent any. The schema is empty, so parameter semantics are inherently covered (baseline 4). The description enriches understanding by explaining the relevance of integration IDs, even without parameter syntax details.

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

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

The description clearly states the tool's function as listing the user's saved credentials (Global Integrations). It details how these credentials are used (referenced by ID) and distinguishes itself from sibling list tools by focusing on integration credentials. The purpose is immediately evident and unambiguous.

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

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

Explicit guidance is provided: 'ALWAYS call this before creating any bot project or asking the user for a token/API key.' It also outlines the fallback procedure when nothing suitable is saved, directing the user to add integrations via settings rather than pasting tokens in chat. This clearly communicates when to use the tool and what alternatives to avoid.

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. The description goes further by revealing that 'values are masked (secrets are never returned)' and enumerates the fields shown, which informs the agent about output behavior and safety. No contradiction with annotations.

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

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

The description is concise and front-loaded with the action. It uses three short paragraphs to cover purpose, use case, and distinction from global integrations, with no filler.

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

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

For a simple, one-parameter list tool with an output schema, the description covers the input, output fields, safety behavior, and relationship to a sibling tool. No important context 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% with the single parameter project_id described as 'the project to inspect.' The description does not add further semantic detail about the parameter beyond this, so the baseline of 3 applies.

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

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

The description opens with 'List a project's environment variables with their details,' using a specific verb and resource. It also explicitly distinguishes from the Global Integrations sibling tool, making its scope unambiguous.

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

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

Explicitly states when to use: 'Use 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 tool (dreamagent_list_global_integrations) and clarifies the distinction, satisfying the 'when/when-not/alternatives' criterion.

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, covering the safety profile. The description adds that it returns name, ID, type, status, and live domain 'when available', and implies scoping to the user's own projects. No contradictions.

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

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

Two sentences, with the purpose and return fields front-loaded, followed by a high-value usage rule. 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 read-only list tool with one well-documented optional parameter and an output schema, the description provides purpose, return fields, and when-to-use. Covers all essential context.

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

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

Schema coverage is 100% with a rich description of the optional status filter, including a caveat about intermediate phases. The description does not repeat or add param-specific info, so baseline 3 applies.

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

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

Description opens with 'List the user's DreamAgent projects' – a specific verb and resource. It enumerates returned fields and connects to user intents ('see, find, select, or check'), distinguishing it from mutation/status siblings.

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

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

States exactly when to use: 'when the user asks to see, find, select, or check their projects' and gives a critical rule: always list first before modifying when ID is unknown. This provides actionable guidance beyond the obvious.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: it clarifies that the session key is a reference, not an authentication credential or secret, which helps prevent misuse. It also preps the agent for what the return value includes. Slight gap: doesn't mention pagination or limit behavior, but that's not critical for a list tool.

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

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

Three sentences: first states purpose, second explains output and usage, third clarifies the nature of the session key. No fluff, information is front-loaded, and each sentence adds distinct value. Well-structured for an AI agent to parse quickly.

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

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

For a simple listing tool with one well-described parameter and strong annotations, the description is complete. It explains what the tool returns, how to use the returned data, and the nature of the key identifier. The output schema is present, so the description doesn't need to enumerate return fields. It also references sibling tools appropriately, giving full context for the agent's decision-making.

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

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

The schema has a single required parameter (project_id) with a description 'the project.' Schema coverage is 100%, so the baseline is 3. The description adds minimal extra meaning about the parameter, only implying it's tied to 'a project's sessions.' Since project_id is self-explanatory and no other parameters exist, the schema carries the semantic load adequately.

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?

Description starts with a clear verb ('List') and resource ('a project's development sessions'), clarifies they are conversation threads, and distinguishes from siblings by explicitly mentioning how the result feeds into other tools (dreamagent_chat, dreamagent_get_chat_status). This goes beyond a generic list operation and makes the tool's role unambiguous.

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

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

Explicitly explains when to use this tool: to select, continue, or monitor a session. It names the exact alternate tools for each follow-up action (dreamagent_chat to continue, dreamagent_get_chat_status to monitor), giving the agent clear context on when this tool is the right choice versus its 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that lock state is not machine-readable from this endpoint, specifies a procedure to judge staleness, and warns about user confirmation if the project may be open elsewhere. This is critical behavioral context that the agent would otherwise miss.

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

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

The description is front-loaded with the critical 'RECOVERY-ONLY' warning, followed by compact, purposeful sentences. It avoids filler and each sentence contributes to either safety, usage, or staleness judgment. Though two paragraphs long, the density justifies the length.

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

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

Given the tool is a lock-release with safety implications, the description covers purpose, explicit boundaries, staleness verification method, and user-confirmation requirement. An output schema exists, so return values need no explanation. The description is complete for the tool's complexity.

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

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

The schema already provides 100% coverage for project_id with 'the project to unlock.' The description does not add extra meaning about the parameter itself, only about the lock's context. Since the schema handles the parameter semantics, a baseline of 3 is appropriate.

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

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

The description opens with 'RECOVERY-ONLY — releases a project's editing lock when a stale or abandoned session blocks new modifications,' which identifies the verb (releases), resource (editing lock), and specific condition. It clearly sets it apart from normal editing tools and sibling tools like dreamagent_chat by emphasizing it is not a standard operation.

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

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

The description provides explicit when-to-use guidance ('when a stale or abandoned session blocks new modifications') and when-not-to-use ('NOT a normal editing step', 'NEVER a way to bypass an actively running edit'). It also directs the agent to an alternative tool (dreamagent_get_edit_progress) for staleness checks and advises user confirmation, satisfying the need for alternatives.

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