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

Annotations declare destructiveHint=true and idempotentHint=false, and the description corroborates by covering removal and replacement. It adds genuinely useful non-obvious behavior: untouched files stay as-is, uncompiled code is saved but never published, and feature edits leave the live lambda untouched. It doesn't state permission requirements or reversibility of a saved version.

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

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

Well front-loaded with the core capability first, then workflow detail. The feature sentence is a dense run-on ('...the way to work on a lambda that exists: change it as often as you like, deploy: true to try it... merge_feature when it is right') that takes effort to parse, but no sentence 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?

For a 9-parameter mutation tool with no output schema, the description covers the workflow (feature vs version, deploy, check) that the schema alone cannot express. It leaves the multiplexed add/replace/remove ordering only partially covered, but is otherwise sufficient to invoke 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 baseline is 3, but the description adds real meaning: it clarifies that feature changes an existing feature rather than saving a new version, that check compiles without publishing, and that deploy targets preview vs public addresses. These distinctions go beyond the per-parameter schema text.

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

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

The description opens with a specific verb and resource: 'Change some files: add or replace files, remove files, or replace text within a file.' That precisely enumerates the three mutation modes. It doesn't explicitly contrast itself with siblings like write_code or upload_file, which an agent must still disambiguate on its own.

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?

Strong conditional guidance for the feature workflow: use feature to edit an existing lambda, 'deploy: true to try it at the feature's preview address, merge_feature when it is right,' and without feature a new version is saved. It also states when check applies. It stops short of telling the agent when to prefer this over write_code.

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