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

Beyond the destructiveHint/readOnlyHint annotations, the description discloses that the previous file set is replaced wholesale, how files are treated by type (lambda.cs handler, other .cs compiled, everything else served as an asset reachable as Assets), and that specification/change are read by the owner in version history. That is meaningful behavioral context an agent could not infer from annotations alone.

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 primary action and its replacement semantics lead, followed by alternatives and parameter guidance in a compact flow. It is somewhat dense with many clauses in a single breath, but nearly every clause carries decision-relevant information.

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

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

For a 5-parameter mutation tool with no output schema, the description covers the mutation's destructive scope, file-type handling, the deploy side effect, the alternative tools, and the purpose of the two free-text fields. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds intent beyond the schema: it explains why specification and change must be written (the owner reads them in version history) and clarifies the handler-vs-types-vs-assets distinction for file names. Minor duplication of the schema's lambda.cs-first ordering keeps it from a 5.

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 opening sentence gives a precise verb and resource: 'Save all files of the lambda as a new version, replacing the previous set.' It distinguishes itself from the two nearest siblings by name, routing partial edits to change_code and large data files to upload_file.

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

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

Explicit when-to-use and when-not-to-use guidance is present: use change_code 'to change only some files', and route large data (models, datasets, media) to upload_file in the workspace. It also states the condition for immediate publishing ('Pass deploy: true to publish it in the same call').

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