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

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses critical behavior: the API cannot list or delete projects, so the returned scriptId is the only handle; the initial project contains only a default manifest and empty Code file; and it requires specific scopes/API toggle plus parent-file access for bound projects. This is exactly the kind of non-obvious operational context an agent needs.

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 minimal but every sentence earns its place: core action, mode distinction, project state, irreversible handle warning, and prerequisites. The 'IMPORTANT' warning is well placed and the progression from behavior to requirements is logical. Slightly verbose, but not wasteful; a 4 reflects the density over brevity tradeoff.

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 lacking an output schema, the description names the return fields (scriptId, title, createTime). With full parameter schema coverage, annotations present, and this rich behavioral text covering side effects, permissions, and post-creation state, nothing an agent needs to call this tool correctly is missing. Bound-project requirements and the workaround for missing list/delete endpoints are especially valuable.

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 substantial meaning for parent_id, explaining that omitting it creates a standalone project whose scriptId doubles as the Drive file id, while providing it binds the project and enables container-specific APIs with a concrete example (SpreadsheetApp.getActive()). This goes beyond the schema's terse 'Drive file id...' and justifies a 4.

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: 'Creates an Apps Script project and returns it (scriptId, title, createTime).' This unambiguously distinguishes create_project from sibling read/update tools like get_project and update_project_content, especially with the explicit chaining instruction 'add real code with update_project_content next.' The scope is precise and immediately usable.

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 both modes: standalone versus bound via parent_id, including the exact Drive file types and the container-specific API benefit. It also directs the next step to update_project_content, which implies the creation-only role. It stops short of explicitly listing exclusion cases (e.g., 'do not use for X'), so it earns a 4 rather than 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 indicate non-idempotent, non-read-only, open-world behavior, and the description adds crucial context: versions are immutable, every call creates a NEW version, version numbers only grow, and creating a version does not change what runs anywhere. This goes well beyond the structured 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?

Three dense sentences, front-loaded with the core action and return value, followed by essential warnings and deployment guidance. Every sentence earns its place without wasted words.

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

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

With no output schema, the description appropriately enumerates the return fields. It also covers immutability, non-idempotency, retry guidance, and the follow-up deployment action, leaving no significant gap for an agent to misuse the tool.

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

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

Schema description coverage is 100%, so the parameters script_id and description are already fully documented. The description's mention of the return fields relates to output rather than parameter meaning, so it adds no additional parameter 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 states a specific verb and resource: 'Snapshots the project's current HEAD content as a new immutable version and returns it.' It also clarifies that versions cannot be edited or deleted, clearly distinguishing this from read-only sibling tools like list_versions or get_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?

It explicitly tells the agent not to re-send after an ambiguous failure without checking list_versions first, and explains that shipping the version requires manage_deployments. This gives concrete when-to-use, when-not-to-use, and alternative-tool guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds useful behavioral context by stating that parentId appears only for bound projects and that no code content is included, which helps the agent set expectations beyond the schema.

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 deliver the return fields, the key exclusion, the sibling alternative, and the primary use cases. Every sentence earns its place, with the most important information 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 single-parameter read-only metadata tool, the description covers what is returned, what is not returned, when to use it, and what to use instead. Annotations handle the safety and idempotency context, and the input schema fully defines the parameter. Nothing critical 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 the script_id property is already well-documented with format and source guidance. The tool description adds minimal parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a precise verb ('Returns') and resource ('project's metadata'), enumerates the exact fields returned, and explicitly differentiates itself from get_project_content by noting no code is included. This makes the tool's purpose unmistakable and distinct from its siblings.

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

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

It provides clear context for when to use this tool: to verify a scriptId exists and to check whether a project is standalone or bound. It also names an alternative (get_project_content) for when file contents are needed. It doesn't enumerate every condition for all siblings, but the guidance is sufficient for the main decision points.

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 readOnly, idempotent, and non-destructive behavior, so the description's burden is lower. It adds valuable behavioral context: HEAD is the latest saved code, version_number returns immutable version content, and the file names returned are the exact identifiers used by update_project_content. This goes beyond the 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?

The description is three sentences with no filler. It front-loads the return value, then explains version behavior, then gives the critical usage note about update_project_content. Every sentence earns its place and the length is appropriate for the tool's complexity.

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

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

For a read-only file retrieval tool, the description is complete: it names the return fields, explains the version parameter, and states the relationship to the update workflow. There is no output schema, so the description carries the burden of explaining the response shape, and it does so clearly. Missing details like pagination or error cases are not significant for this tool's scope.

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 already describes both parameters thoroughly (100% coverage), so the baseline is 3. The description adds extra meaning by linking version_number to immutable versions and by noting that returned file names are the exact ones needed for update_project_content. This supplements the schema's parameter descriptions with workflow-level significance.

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 exactly what the tool does: returns the project's full file set with specific fields (files[], name, type, source, per-file update info). It also distinguishes HEAD vs version_number behavior, making the purpose unambiguous. The title 'Get project files' is expanded into concrete details that differentiate it from sibling tools like get_project.

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

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

The description explicitly says to call this before update_project_content and explains why: replace mode needs the full new set including the manifest, and merge mode addresses files by these exact names. It also clarifies when to use version_number versus the default HEAD, giving the agent actionable 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds important behavioral details: each metric is a time series, value is absent when zero, daily covers the last 7 days, and the script.metrics scope is required. It does not contradict 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 dense but every sentence earns its place: purpose, response shape, granularity semantics, deployment behavior, failure-handling cue, and required scope. The main purpose is front-loaded, making it easy to scan.

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 tool with three parameters and no output schema, the description supplies the response format, edge-case behavior for zero values, parameter effects, required permissions, and a concrete follow-up action. An agent has enough information to invoke it correctly and interpret results.

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 already has 100% parameter description coverage, so the baseline is 3. The description lightly reinforces the meaning of granularity and deployment_id, but does not add substantial semantic detail 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 opens with 'Returns execution metrics for the project' and names the specific metrics (activeUsers, totalExecutions, failedExecutions) plus the time-series shape. This clearly distinguishes it from siblings like list_processes and get_project by focusing on aggregate execution metrics.

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 explains when to use each granularity, what deployment_id does, and explicitly says that a rising failedExecutions count is the cue to call list_processes with statuses=[FAILED]. This gives the agent an explicit conditional alternative, not just a vague purpose.

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

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

Annotations already cover the read-only, idempotent, non-destructive safety profile. The description adds meaningful behavioral context by stating versions are immutable and that the endpoint returns metadata only, not code. This goes beyond the 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?

Two sentences with zero filler. The primary function is front-loaded, and the routing to the sibling tool is a single clear clause. 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 metadata retrieval tool with complete schema documentation and strong annotations, the description adequately covers purpose, return fields, and the key alternative. It does not specify an output schema, but listing the returned fields directly compensates for that. Minor gap: no mention of error conditions, but this is not critical for such a simple read operation.

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

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

Schema description coverage is 100%, so the input schema fully documents script_id and version_number. The description does not add parameter-level detail, but it does not need to because the schema carries the burden. 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 uses a specific verb ('Fetches') and resource ('one immutable version by its number'), and explicitly lists the returned fields (versionNumber, description, createTime). It also distinguishes itself from get_project_content by clarifying this endpoint returns metadata only, so an agent can clearly tell them apart.

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 names the alternative tool (get_project_content) and gives the exact condition for choosing it: when you need the code of that version instead of metadata. This is a clear when-and-when-not directive with no inference 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral details: the API returns only failure facts and times, not error messages; with script_id it scopes to one script, without it the scope is all executions by the authorizing user; and it requires the script.processes scope. This is exactly the kind of context that helps an agent anticipate results and avoid misuse.

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

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

The description is dense but every sentence serves a purpose: it states the resource, enumerates return fields, explains scoping behavior, gives error-hunting guidance, covers time/pagination, and notes auth scope. Information is front-loaded and logically organized.

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 listing tool with no output schema, the description is notably complete: it specifies return fields, scoping rules, filtering semantics, pagination, failure behavior, and required OAuth scope. An agent has enough context to call this tool correctly and interpret its results.

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 the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the script_id omission behavior, that start_time/end_time bound process start time, that page_token paginates, and how statuses relate to error hunting. This is a real value-add over the schema alone.

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

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

The description states a specific verb and resource: 'Lists execution processes (the execution history)', and enumerates the exact fields returned. This clearly distinguishes it from sibling tools like list_versions, which list versions rather than execution history.

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 covers when to use this tool, such as filtering 'statuses=["FAILED","TIMED_OUT"]' to hunt errors, and explains a key limitation: no error messages or logs are returned. It names alternatives like run_function and the Apps Script dashboard/Cloud Logging for retrieving actual error messages, giving clear 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?

Discloses behavior beyond the annotations: versions are immutable, returned newest first, and pagination uses page_token from nextPageToken. This adds practical detail about ordering and iteration that annotations alone do not convey.

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, each earning its place: core listing behavior, pagination, and downstream usage. Key details are front-loaded and there is 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 list tool with strong annotations and full schema coverage, the description is complete. It identifies the returned fields, ordering, pagination continuation mechanism, and downstream uses, covering what an agent needs to call 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 coverage is 100%, so parameters are already well documented. The description reinforces page_token usage and mentions versionNumber as an output consumers use, but does not significantly add meaning beyond the schema's parameter descriptions.

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: 'Lists the project's immutable versions... newest first.' It clearly identifies the action, target, and ordering, making it easy to distinguish from sibling tools like get_version and create_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?

Provides clear usage context by explaining when to use this tool, such as picking a versionNumber for manage_deployments or reading old code via get_project_content. However, it does not explicitly mention when not to use it or name get_version as the single-version alternative.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, but the description adds critical behavior beyond that: delete permanently breaks URLs/integrations, update merges config so omitted fields are preserved, HEAD deploys update live with every save, and the automatic @HEAD deployent cannot be deleted. There is 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 dense but every sentence earns its place: domain definition, action-by-action semantics, edge cases, prerequisite, and scope. It is front-loaded with purpose and avoids redundant restatements of the 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 a five-action tool with no output schema, this description covers action selection, parameter semantics, destructive consequences, undeletable edge case, cross-tool prerequisite, and required OAuth scope. An agent can correctly invoke any action without needing to look up additional 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%, so the baseline is already strong. The description adds action-param binding: version_number can be omitted to deploy HEAD, page_token comes from nextPageToken, get requires deployment_id, update uses version_number and/or description with merge semantics. It doesn't add much for script_id or page_size, but the schema adequately covers those.

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 clearly defines deployments as published entry points (web app, API executable, add-on) and then maps every action—create, list, get, update, delete—to a specific behavior and target. It distinguishes this tool from sibling tools like create_version and run_function by scoping it to the deployment lifecycle.

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

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

It gives explicit when-to-use guidance per action: create to deploy a version or HEAD, list to see all deployments with pagination, get to fetch entryPoints, update to ship/rollback while preserving URL, delete to permanently remove. It also states when-not-to: @HEAD cannot be deleted, and HEAD is risky for production. The prerequisite via update_project_content and required scope are also stated.

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 destructiveHint=true and openWorldHint=true, and the description adds valuable behavioral context: the Bearer token is added automatically, foreign-origin paths are rejected, the method defaults to GET, and PUT content replaces the entire file set. This complements the 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?

The description is five sentences long, and every sentence earns its place: purpose, examples, query-string handling, auth/origin/method behavior, and the destructive PUT warning. It is front-loaded with the escape-hatch purpose and contains 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 raw API escape hatch with no output schema, the description sufficiently covers usage, authentication, origin safety, method default, and destructive behavior. It does not mention response format or error handling, but these are reasonably implied for a direct API pass-through and the risky PUT case is explicitly flagged.

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 goes beyond the schema by explaining that paths may carry query strings, repeated filter params can be encoded there, and giving concrete path/body examples. It doesn't deeply document the body shape, but the examples compensate 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?

The description opens with a specific verb and resource: 'call any Google Apps Script API v1 path directly' and frames itself as an 'escape hatch' for 'requests the typed tools don't cover'. This clearly differentiates it from typed siblings, and concrete examples (GET content, PUT content) remove any ambiguity about what the tool does.

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

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

It explicitly states when to use the tool: when typed tools don't cover a request. It also provides a when-not by naming update_project_content as the preferred alternative for PUT content, because its merge mode protects other files. Query-string usage and the GET default are also explained.

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 goes well beyond the annotations by explaining the script_error return shape, distinguishing script bugs from transport errors, warning against blind retries due to possible side effects, spelling out OAuth/GCP prerequisites, and disclosing the timeout. The destructiveHint annotation is consistent with the side-effect warning.

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 every sentence carries important operational information. It is front-loaded with the core action and return type, though the dense paragraph structure and heavy parentheticals make it slightly harder to scan.

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 remote-execution tool with no output schema, the description is exceptionally complete: it covers return shapes, error taxonomy, side effects, prerequisites, permission failures, parameter constraints, dev_mode semantics, and timeout. An agent has enough information to call this correctly and diagnose failures.

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 description only needs to add marginal meaning. It mostly restates what the schema already says about parameters being positional, JSON-serializable, and dev_mode being owner-only, rather than introducing new parameter-level 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 opens with a specific verb and resource: 'Runs a named function in the script' and clarifies the return contract ({ done, result } or { done, script_error }). This clearly differentiates run_function from the project-management and setup-related sibling 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 gives clear operational context: hard prerequisites, dev_mode owner-only behavior, positional JSON-serializable parameters, and the 6-minute timeout. It does not explicitly name alternatives or state when not to use this tool, but the context is strong enough to guide correct selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond those flags: it is safe to call without credentials, it returns structured JSON, and it exposes known API limits. Nothing about the tool's observable behavior is hidden or contradicted.

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

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

The description is a single dense sentence that front-loads the core purpose and then enumerates the checklist contents and usage trigger. It is longer than the minimal alternative but every clause carries distinct information about setup prerequisites, scopes, and API limits. A slight structural split into two sentences would improve readability, but no content is wasted.

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

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

Given zero parameters, rich annotations, and no output schema, the description is fully complete: it tells the agent what the tool returns, the specific setup facts the checklist covers, that no credentials are needed, and exactly when to invoke it. An agent can confidently decide to call this tool and understand what it will receive.

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 parameter baseline is 4. The description goes further by explaining the content of the returned checklist and the conditions under which the tool should be invoked, which compensates for the absence of an output schema. There is nothing more parameter semantics could add with an empty input 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 immediately states the tool 'Returns the setup checklist for this server as structured JSON' — a specific verb, resource, and output format. It enumerates exactly what the checklist covers (Apps Script API enablement, OAuth scopes, run_function prerequisites, API limits), and its purpose is clearly distinct from all sibling tools, which operate on projects, versions, functions, or raw requests.

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: 'call it first when any tool fails with 403 PERMISSION_DENIED or when setting the server up.' It also notes 'Works without credentials,' which tells the agent this tool is safe to invoke in unauthenticated or failure contexts. This fully routes the agent to the correct first step.

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 indicate destructive and non-read-only behavior, but the description goes much further: it explains the read-modify-write race in merge mode, the total deletion semantics of replace mode, the mandatory appsscript manifest, rejection before API call if missing, and the lack of automatic retries after 5xx/timeout. It also discloses the naming convention and the fact that the manifest cannot be deleted. No contradiction with annotations exists.

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

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

The description is dense but every sentence adds essential information: the main effect, the two modes, merge semantics, replace semantics, naming/manifest constraints, return value, and retry behavior. It is front-loaded with the primary purpose and avoids filler or repetition.

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

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

For a mutating tool with no output schema, this description covers all critical aspects: the operation, mode behavior, preconditions, constraints, return value, and failure handling. Even though the schema documents each parameter well, the description supplies the missing behavioral context needed to call the tool safely and 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 the baseline is 3. The description nevertheless adds operational meaning beyond the schema: it clarifies that files are upserted BY NAME, that delete_files only applies to merge mode, that the manifest is required in replace mode, and that names carry no extension. These are useful execution details directly tied to parameters.

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: 'Writes code files to the project's HEAD.' It also clearly differentiates from deployment-related siblings by noting deployed versions remain untouched until a version and deployment are created. The two modes are named and their effects are distinguishable, so an agent knows exactly what operation this tool performs.

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 concrete usage context for both modes: merge is the default and safer option, replace makes the files the entire project. It also references the appropriate sibling tool for recovery ('check with get_project_content before re-sending') and explains when deployed content changes, connecting to create_version/deployment workflow. This gives explicit when-to-use and when-not-to-use guidance.

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