Aurora

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

Annotations already mark destructiveHint=true and readOnlyHint=false; the description adds valuable behavioral context beyond that: atomicity (nothing written if any edit fails), error naming the offending file, the 50-change limit, and the dev-server requirement. 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?

Four sentences with no filler: purpose, usage, failure semantics, and prerequisite are each covered in one tight sentence. The most important scoping information is front-loaded.

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

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

Given full schema coverage, an output schema, and annotations, the description covers prerequisites, limits, atomicity, and failure behavior. Nothing essential for an agent to invoke the tool 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%, so the schema fully documents the three change shapes, commit message, and project_name. The description adds behavioral context (exact old-text matching, atomic failure) but no new parameter-level semantics, 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?

States a specific verb and resource ('Create, edit, or delete files in a project') and clearly distinguishes itself from read-only siblings by emphasizing 'one commit' and 'change a project's code directly.' The scope is unambiguous.

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

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

Explicitly says 'Use this to change a project's code directly,' which gives a clear when-to-use signal. It also notes a prerequisite (running dev server). It doesn't name alternatives or exclusions, but the context is sufficient for an agent to select it over read_file or deploy.

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

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

The description discloses that the tool edits the project and commits the result, which aligns with destructiveHint=true and readOnlyHint=false. It adds valuable unannotated behavior: turns can take minutes, after ~40 seconds a job_id is returned, and the work continues asynchronously.

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 with no filler: the first gives the core action, the second gives usage examples, and the third explains timing, return behavior, and the async path. The most important scoping detail is front-loaded.

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

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

For a long-running agent tool with two schema-documented parameters and an output schema, this description covers selection, invocation, expected returns, and the asynchronous job_id behavior. An agent has enough context to call it correctly and to know what to do when it takes longer than expected.

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?

Both parameters are fully described in the input schema, so the description does not need to add much. The phrase 'described in plain words' lightly reinforces the message parameter, but no additional parameter-level semantics are provided beyond what the schema already covers.

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

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

The description states a clear action ('Send a task to Aurora's AI agent') and resource ('the project'), then gives concrete use cases: build a feature, change a design, or add an npm package. It also distinguishes itself from the chat_status sibling by explaining the job_id flow.

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

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

The description explicitly says when to use the tool ('Use this to have Aurora build a feature...') and mentions the chat_status fallback for long-running turns. It does not explicitly list when-not-to-use scenarios or compare against other siblings like apply_changes, but the intended context is clear.

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

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

Annotations declare readOnlyHint=true, matching description (polling/status). Description adds crucial behavioral detail: waits up to 40 seconds, returns result when done or progress/files changed so far. This goes beyond the annotation, revealing async behavior and partial results. No contradiction.

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

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

Two short paragraphs; first states purpose, second explains waiting behavior and return conditions. Front-loaded with purpose, zero waste. Every sentence adds 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 output schema exists (not detailed here but indicated), description explains the timing and partial-result behavior, which is the key uncertainty. With readOnlyHint and full schema coverage, this is complete for an agent to call it correctly.

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

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

Schema coverage is 100% for job_id, with a straightforward description. The description adds that job_id comes from chat, which is already implied by the schema ('The job_id that chat returned'), but reinforces the origin. No additional elaboration needed.

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?

Clear verb (get) and resource (chat status/turn result). Ties to job_id and sibling chat. Distinguishes from get_deployment_status and get_dev_logs clearly. Title matches description.

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 it retrieves the result of a chat turn by job_id, implying it should be used after starting a chat. Doesn't explicitly mention when not to use or alternatives, but siblings are distinct enough. It mentions waiting behavior, which guides usage.

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

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

With annotations only indicating readOnlyHint=false and destructiveHint=false, the description carries the burden of explaining behavior. It does so well: it states side effects (GitHub repo creation, publishing to a public URL), the starting template, and the option to seed from existing files. It returns the project name and preview URL, which is also helpful behaviorally.

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

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

The description is front-loaded with the core action and product scope, followed by concrete capabilities, a usage fit statement, and a return-value note. Every sentence adds distinct information; none are filler. It is detailed yet compact given the complexity of the tool.

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

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

For a complex creation tool with an output schema present, the description covers the essential decision points: what gets created, when to use it, how existing code can be supplied, and what is returned. It does not go into limits like timeouts or preconditions, but the rich schema plus output schema make the description sufficiently complete for invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds extra context by explaining that the app 'starts from a TanStack Start + React + Tailwind template, or from existing code passed in files,' which complements the files parameter meaningfully. It also signals that a short prompt is the main input, and clarifies the return payload, giving semantic weight beyond the raw JSON schema.

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

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

The description opens with a specific verb and resource: 'Create a full-stack web app that runs outside the chat.' It enumerates exactly what is created (server, backend, user accounts, APIs, preview URL, GitHub repo, publishing) and distinguishes this from sibling tools like deploy, start_dev_server, or apply_changes by establishing that this is the full project creation entry point.

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 clear when-to-use context: 'Fits when the user wants an app other people can use, data that persists, or a real website.' It does not explicitly name alternative tools or say when not to use it, but the use-case framing plus the sibling list is enough to route an agent correctly.

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?

Adds important behavioral detail beyond the annotations: the production build runs in the background, the tool returns 'building' immediately, and status must be checked separately. The 'Free accounts keep one live deploy' note hints at potentially replacing an existing deploy, aligning with destructiveHint=true.

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 and front-loaded with the core purpose. Every sentence earns its place: purpose, trigger phrases, async behavior, status-checking route, and account limit.

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 deployment tool with an output schema and sibling status tool, the description covers the essential workflow: it publishes asynchronously, returns a building status immediately, and directs the agent to get_deployment_status for the outcome. The free-tier one-live-deploy limitation is a valuable contextual detail.

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 both parameters with descriptions, so the baseline is 3. The tool description does not add any parameter-specific guidance about subdomain formats or project_name resolution, but none is strictly needed given the 100% schema coverage.

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

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

States a specific action and resource: 'Publish a project to a public production URL.' It also clarifies when the tool is meant to be used ('deploy, publish, or go live'), and the immediate-return behavior differentiates it from get_deployment_status.

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 says to use this tool when the user asks to deploy, publish, or go live. It also points to get_deployment_status for checking the result. It does not explicitly contrast with redeploy, but the usage context is clear enough for most cases.

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

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

The annotations already declare readOnlyHint, and the description adds meaningful behavioral detail: the exact returned status values and the fact that a failed deploy includes the end of the build log. This goes beyond the structured annotation without contradicting it.

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, each carrying distinct information: purpose, return values, and failure behavior. There is no fluff, and the main purpose is front-loaded.

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

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

For a one-parameter, read-only status tool with an output schema available, the description covers what the tool does, what it returns, and the special failed case. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100% and the only parameter, project_name, is already documented as 'Name of the project.' The description does not add additional format, source, or validation detail, so it stays at the schema-driven baseline.

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 explicitly states a specific verb ('Check') and resource ('a project's production deploy'), then lists the concrete outputs: status, public URL, and build errors. This clearly distinguishes it from sibling action tools like deploy or redeploy and from dev-log tools.

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

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

The description implies the tool should be used when you need to know whether a production deployment is building, live, or failed, but it does not explicitly state when to use it over alternatives like get_dev_logs or redeploy. There is no exclusion or conditional routing, so guidance is only implied.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds valuable behavioral detail by specifying what the logs contain (build errors, server errors, other output) and that it reads the latest lines, going beyond the bare annotation.

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

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

The description is three short sentences with no filler. It front-loads the resource, then discusses return content, then the use case. Every sentence contributes to correct invocation.

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

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

For a simple read-only tool with two parameters and a documented output schema, the description sufficiently covers the resource, the purpose, the type of returned information, and a typical usage scenario. Missing details like behavior when the dev server is not running are minor given the tool's simplicity.

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 parameters (lines and project_name) already clearly documented in the schema. The description adds little param-specific meaning, but that is acceptable because the schema carries the full semantic burden.

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

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

The description uses a specific verb ('Read') and resource ('latest output of a project's dev server'), and further clarifies the content by listing build errors and server errors. This makes it distinguishable from sibling tools like start_dev_server or restart_dev_server, though it does not explicitly name those alternatives.

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

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

The description gives a clear invocation context: 'Useful after a code change to confirm that the project still builds.' This implies when to use the tool relative to development workflows, though it does not explicitly say when not to use it or mention alternative tools.

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

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

Annotations already mark readOnlyHint=true, covering the safety profile. The description adds useful behavioral context: the tree is capped at top 3 levels, and the returned paths are directly compatible with read_files and apply_changes, revealing both a depth limitation and the output's downstream contract. 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?

Two tightly constructed sentences with no filler. The core purpose and depth limit are front-loaded, and the path-compatibility detail clearly earns its place by connecting to sibling tools.

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, read-only, output-schema-backed tool, this description is sufficient: it states the depth limit and the output's downstream use. The annotations cover safety, and the output schema covers return format, so nothing essential 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%: project_name is described as 'Name of the project'. The description adds no additional parameter-level guidance (e.g., where to obtain a valid project_name), but with full schema coverage the baseline of 3 is appropriate.

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

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

States a clear verb ('List'), resource ('a project's files and folders'), and a scope ('top 3 levels'). It explicitly ties the output to the exact paths accepted by read_files and apply_changes, distinguishing it from sibling tools like list_projects and read_files.

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

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

The description doesn't explicitly enumerate when to use or avoid alternatives, but it establishes clear context: the output is defined as the exact paths read_files and apply_changes take, implying this tool is the prerequisite for those operations. It lacks explicit exclusions, hence not a 5.

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 the description adds useful behavioral context beyond that: the preview URL always shows the latest code and the dev server state reflects whether the preview is running. This helps an agent interpret results without contradicting the read-only annotation.

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

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

The description is two short sentences with no filler. The main output is front-loaded, and the second sentence adds valuable clarification about the preview URL and dev server state. Every 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?

For a simple read-only tool with one well-documented parameter and an output schema, the description is complete. It explains the meaning of the key outputs, and the annotations cover the safety profile. No critical information needed to invoke it correctly is missing.

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

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

The input schema has 100% description coverage for the single parameter 'project_name' ('Name of the project'). The tool description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states the verb 'Get' and the resource: a project's status, preview URL, and dev server state. This is specific enough to distinguish it from siblings like get_deployment_status or get_dev_logs, though it does not explicitly name those alternatives.

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

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

The description gives clear context for using the returned data: the preview URL is the link for work in progress, and the dev server state indicates whether the preview is running. It does not explicitly discuss when to choose this tool over siblings, but the context is sufficient for basic 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?

The description adds behavioral detail beyond the readOnlyHint annotation by outlining the return content (summary of capabilities, workflow, conventions). It does not contradict the annotation and provides concrete expectations for the agent, even though no safety or side-effect concerns apply.

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: a two-sentence structure that front-loads the primary purpose and then elaborates on the return content. Every sentence contributes value, with no filler or 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?

The description is complete for a read-only informational tool with no parameters and an output schema. It explains what it returns and when to use it, leaving no gaps in the agent's understanding of how and when to invoke it.

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

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

The tool has zero parameters, so the schema fully covers the input. The description does not need to explain parameter semantics; the baseline score of 4 applies because no parameters exist and schema coverage is 100%.

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 that the tool returns a summary of what Aurora can do, its workflow, and project conventions. It specifies the exact content (examples, free plan, creation-to-deploy process, code conventions) and distinguishes itself from sibling tools that focus on project data (e.g., get_project, list_projects).

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

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

The description explicitly states when to use the tool: "when the user asks what Aurora can do" and "before the first code change in an Aurora project." This gives clear context, though it does not mention alternatives or when not to use it. Given the tool's unique role among siblings, the guidance is sufficient.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds context beyond that by specifying the output fields (name and status) and the fact that the output serves as the source of project_name for other tools. This is useful behavioral context, though it does not elaborate on potential limitations or edge cases, which are minor for a read-only list operation.

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

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

The description is two sentences with no redundant words. The primary purpose is stated first, followed by essential usage guidance. Every sentence earns its place, and the structure is efficient and front-loaded.

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

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

For a simple parameterless list tool, the description covers the purpose, when to use it, and how its output feeds other tools. Since an output schema is present, the return format does not need to be described. There are no missing details an agent would need to invoke 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?

The input schema has zero parameters, so there is nothing to document. The schema description coverage is trivially 100%, and the baseline for zero parameters is 4. The description does not need to add parameter details because none exist, and it correctly focuses on the output usage rather than inputs.

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 a specific action (list) on a specific resource (projects) and specifies the returned attributes (name and status). It distinguishes itself from siblings by explicitly noting that other project tools rely on the project_name from this list, so an agent can immediately understand its role.

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

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

The description explicitly instructs when to use the tool ('when the user refers to an app that already exists') and explains how it relates to sibling tools ('The other project tools take the exact project_name from this list'). This gives clear guidance on when to invoke it versus alternatives, 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 already declare readOnlyHint=true, covering the non-mutating nature. The description adds useful context that the full file contents are returned, suggesting no truncation or pagination. However, it does not cover details such as file size limits, encoding, or error behavior, but this is acceptable given the simple read operation and existing annotation coverage.

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, no wasted words. The primary purpose is front-loaded, and the sibling differentiation appears immediately after. Every 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?

For a simple single-file read operation, the description covers the core behavior and differentiates from the batch sibling. Annotations provide the read-only safety profile, the schema fully documents both parameters, and an output schema exists, so nothing essential is missing for an agent to select and invoke this 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 description coverage is 100%: file_path is defined as 'Path relative to project root' and project_name as 'Name of the project'. The description adds no additional parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

States the specific action 'Read one file from a project' and the result 'return its full contents'. It clearly distinguishes itself from the sibling read_files by explicitly noting that a single file is read, and the second sentence highlights the sibling's batch capability.

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

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

The second sentence, 'read_files reads up to 20 files in one call', provides clear context about the alternative tool and implies when read_file is appropriate (single file) versus read_files (multiple files). It stops short of an explicit 'use read_files when you need more than one file', but the guidance is easy to infer.

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, so the description does not need to repeat that. The description adds useful behavioral context: it returns full file contents and that these contents are the exact text to match against for apply_changes edits. It also discloses the 20-file limit, which is a functional constraint beyond the schema. This adds meaningful context without contradicting 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 two sentences with zero fluff. It front-loads the primary purpose and the key constraint (20 files), then provides a practical reason for the return value. Every 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?

The tool has an output schema (indicated by context signals), so return-value details are covered there. The description covers the essential usage constraints (20 files, relative paths, full contents) and the apply_changes matching context. It does not discuss error conditions or edge cases, but for a read-only tool with a simple interface, this is adequate. It slightly misses explicitly contrasting with read_file, but that is not critical for completeness.

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 two parameters, so the schema already documents their meaning and constraints. The description does not add additional parameter-level detail beyond what is in the schema; the mention of 'up to 20' is already in the file_paths description. Since the schema carries the weight, a baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('Read up to 20 files from a project in one call') and the resource. However, it does not explicitly differentiate from the sibling tool 'read_file' (singular), though the name and the 'up to 20' limit imply the distinction. It is clear but lacks explicit sibling differentiation.

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

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

The description implies usage by mentioning that the returned text is what 'apply_changes' matches against, suggesting a primary use case. However, it does not explicitly state when to use this tool versus alternatives like 'read_file', nor does it mention any exclusion conditions. The guidance is only implied through the apply_changes context.

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

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

Annotations already flag destructiveHint=true; the description adds asynchronous behavior: 'The build runs in the background: this returns "building" at once, and get_deployment_status reports the result.' This discloses the immediate return value and the follow-up mechanism, going 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?

Three sentences, front-loaded purpose, then usage, then behavior. Every sentence earns its place, with no repetition of schema or annotations.

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

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

For a single-required-parameter mutation tool with an output schema, the description covers the prerequisite ('already deployed'), the trigger conditions, and the asynchronous behavior with a pointer to get_deployment_status. Nothing necessary for correct invocation 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%: the only parameter project_name is documented as 'Name of the project.' The description adds no parameter-level meaning, so the schema carries the semantic burden. 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+resource: 'Update the live site of a project that is already deployed.' The qualifier 'already deployed' distinguishes it from the sibling deploy, and it names get_deployment_status as the status-checking counterpart.

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 this when the user asks to update the live site, or to retry a failed build.' It lacks explicit when-not-to-use or a named alternative for the same operation, but the trigger conditions are 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 signal write/destructive behavior, so the description earns credit for adding useful context: it restarts with fresh environment variables and fails with 'Container not found' when the server is not running. This goes beyond the schema and annotations without contradicting them.

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

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

Three short sentences, each carrying distinct value: what the tool does, when to use it, and a known failure mode. No filler or 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?

For a single-parameter restart tool, the description is complete: it explains the action, the fresh environment variable behavior, when to invoke it, and the expected failure mode when the server is absent. The output schema and annotations cover the remaining structured information.

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

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

The schema already documents project_name with 100% coverage, so the description does not need to add parameter-level detail. The description adds no meaning beyond the schema, which is acceptable at the baseline.

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

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

The description states a specific action and resource: 'Restart a running preview server with fresh environment variables.' This clearly distinguishes it from siblings like start_dev_server and redeploy by specifying 'running' and 'preview server.'

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

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

The description explicitly says when to use it: 'after project secrets change, or when the preview is stuck.' It does not explicitly name alternatives or state when not to use it, but the failure condition implies that start_dev_server is the alternative if the server is not running.

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

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

The description adds meaningful behavioral detail beyond the annotations: it discloses the asynchronous acceptance semantics ('returns when the start is accepted') and the latency window ('usually running within 30 to 90 seconds'). The idempotent behavior for already-running servers is consistent with and reinforces idempotentHint=true. It does not repeat the annotation fields verbatim, adding real value.

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

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

Three short sentences, each earning its place: the core purpose, the lifecycle/timing context, and the idempotency caveat. The most important information is front-loaded and there is zero wasted wording.

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

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

For a single-parameter tool with a 100%-covered schema, an output schema, and annotations covering the safety profile, the description is complete. It tells the agent when to call it, what timing to expect, and how it behaves on an already-running server. 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 description coverage is 100%, so the schema already documents project_name as 'Name of the project.' The description adds no parameter-specific meaning beyond the schema, which is acceptable given full schema coverage. 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 opens with a specific verb+resource statement: 'Start a project's preview server.' It further differentiates from siblings by explaining the lifecycle context ('Aurora stops the preview server of an idle project') and explicitly contrasting with restart behavior ('A server that is already running is left alone'), which distinguishes it from restart_dev_server. An agent can tell exactly what this tool does and what it does not do.

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 clear context for when to use the tool: when an idle project's server has been stopped by Aurora and needs to be started again. It implies the exclusion that it is not for already-running servers ('is left alone'). However, it does not explicitly name the alternative (restart_dev_server) or state when that sibling would be preferable, so it stops short of a full 5.

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