GenHTTP Lambda

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

Annotations declare destructiveHint=true and non-idempotent, so the safety profile is partly covered. The description usefully adds the versioning model (edits are saved as a NEW version rather than mutating in place) and the inline-deploy capability, which the annotations do not convey. It does not describe error behavior or what happens to prior versions beyond the new-version framing.

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 tight sentences, front-loaded with the core action and edit modes, then the key differential behavior, then the deploy tip. No filler or restatement of the title.

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 7-parameter mutation tool with no output schema, the description covers versioning, differential editing, and inline deploy well. It omits what the call returns (e.g. the new version identifier an agent would need to chain into deploy or read_lambda), 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 the baseline is 3, but the description adds meaning beyond the schema: it clarifies that omitted files are left intact and that deploy: true publishes in the same call. It does not explain edit ordering (the schema notes edits apply after files/remove) or the privateKey/change/specification 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?

States a specific verb and resource ('change some files of the newest version and save the result as a new version') and enumerates the three edit modes (add/replace, remove, text replace). It implicitly differentiates from write_code by noting unchanged files need not be resent, but never names the sibling, so an agent must infer the distinction.

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?

Gives clear context for incremental editing ('Everything not named stays as it is, so there is no need to resend unchanged files') and a usage tip for combining publish with the edit via deploy: true. No explicit when-not guidance or named alternative (e.g. write_code) is provided.

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 safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description adds real value by disclosing that diagnostics carry file and line, and that the handler is not built so deploy may still reject a route. That limitation is exactly the kind of nuance annotations cannot express.

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 dense sentences with the primary behavior first and the important limitation second; no restatement of the name or title and 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 two-parameter, read-only compile check with no output schema, the description covers what is returned (diagnostics with file and line), what is not persisted, and where the check's authority ends. Nothing needed to invoke or interpret it 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 properties (name, code, encoding, privateKey) are already documented, and the description adds no syntax or format detail about them. Baseline 3 applies when the schema carries the 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?

States a specific verb and resource (compile the submitted code) and immediately scopes it as a non-persisting dry run, which cleanly separates it from write_code, change_code, and deploy. An agent can tell what it does and does not do without opening the schema.

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 phrase 'without saving or deploying' signals this is the pre-flight alternative to write_code/deploy, and the closing sentence explains the boundary case where deploy can still fail after a successful check. It gives clear context but never names the sibling tools or states an explicit 'use this instead of X' rule.

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 safety profile (not read-only, not idempotent, not destructive, closed-world). The description adds genuinely non-redundant behavior: it discloses the return payload and warns that the private editor key is 'the only way back in' and that nothing is live until deploy. It could say more about auth/terms requirements and repeat-call effects.

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 tight sentences, front-loaded with the action, then returns, then the key constraint. No filler, and each sentence carries distinct 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?

With no output schema, the description correctly fills the gap by explaining what creation returns (public address, editor key). It covers the create/deploy distinction and the irrecoverable-key warning. It stops short of noting any permission or terms prerequisites beyond what the schema's acceptTerms field already carries.

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 all three parameters (template, publicKey, acceptTerms) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, 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?

States a specific verb and resource ('Create a lambda') plainly. It also implicitly distinguishes itself from the sibling 'deploy' by noting 'Nothing is online until deploy', so an agent can separate creation from going live, though no sibling is named explicitly.

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?

There is no explicit when-to-use or when-not-to-use guidance, nor named alternatives. The workflow hint ('Nothing is online until deploy') implies the creation-then-deploy sequence, but this is inference rather than stated 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, covering the safety profile. The description adds value beyond that by disclosing the scope of destruction: deleting a folder also removes its contents, which is not inferable from a generic destructive hint.

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?

A single tight sentence with the resource and the recursive-folder behavior front-loaded. No filler, nothing to trim.

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 two-parameter destructive mutation with rich annotations and no output schema, the description adequately covers what is deleted and that folder contents go with it. It could mention irreversibility or what the privateKey authorization implies, but nothing essential to calling the tool 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 both parameters (path, privateKey) are documented in the schema. The description only echoes the workspace scoping already stated in the path schema, adding no new syntactic or format detail, 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?

States a specific verb (remove) and resource (file or folder with contents) scoped to the workspace, so an agent immediately knows what the tool does and that folder deletion is recursive. It doesn't explicitly name or contrast with siblings (list_files, upload_file), but the operation 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?

There is no when-to-use / when-not-to-use guidance, no prerequisites, and no warning that the operation is irreversible. Sibling names are not referenced, so the agent gets no routing help beyond the verb itself.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds one genuine behavioral detail ('Returns diagnostics on failure'), but never says that deploying replaces the currently live version or what happens to the prior published content, which is the key thing a destructive deploy would need to disclose.

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 sentences, zero waste, with the core action and outcome front-loaded and the failure behavior appended. Nothing redundant or padded.

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 a complete schema and annotations carrying the destructive/idempotent profile, most of the burden is covered elsewhere. However, for a mutation that overwrites a live public site, the description omits the lifecycle impact and permission expectations, and there is no output schema to explain the diagnostics mentioned on failure.

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 schema documents 'version' defaulting to newest and 'privateKey' as the editor key. The description adds no syntax, format, or semantic detail beyond the schema, so the 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 and resource ('Deploy (publish) a saved version') and clarifies the outcome ('goes live at its public address'), which disambiguates from siblings like upload_file or write_code. It does not, however, name or contrast with any sibling tool, so it stops short of a 5.

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 no guidance on when to deploy versus other lifecycle tools (change_code, check_code, upload_file), nor any prerequisites or sequencing (e.g., that a version must be saved first). Implicitly, 'a saved version' hints at a precondition, but nothing explicit is 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 declare readOnly, idempotent, non-destructive, and closed-world. The description adds meaningful context beyond them: the demo keys are public and read-only, and the demos serve as canonical reference implementations. It does not characterize the return shape or ordering, but for a zero-param read that is minor.

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 with what demos are, then the read path, then the template path. The mid-sentence enumeration of demo categories is slightly listy but earns its place by telling the agent what kinds of reference code exist.

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?

No output schema exists, so the description carries the burden of previewing return content, and it does so by describing demos as finished lambdas with concrete types and public read-only keys. An agent knows what it will get and what to do next; only explicit pagination/ordering detail is absent, which is negligible here.

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?

There are zero parameters and schema coverage is 100%, so the baseline is 4. The description correctly adds no parameter commentary since there is nothing to parameterize.

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 the resource (demos, each a finished lambda) and characterizes what they are with concrete examples (REST API, login, websocket game, uploads). It is clear the tool surfaces this catalog, though it never literally says 'returns a list', leaning on the name/title for the verb. It implicitly distinguishes itself from siblings by framing demos as read-only reference code.

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 routing: read the closest demo with read_lambda (plus list_files, read_logs) before writing similar code, and use create_lambda with a demo's id as template to start from a copy. This tells the agent both the follow-up action and the alternative path, which is exactly what a catalog tool needs.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond them: the listing includes size and last-write metadata and excludes code files, which tells the agent what the output contains and what it omits.

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 sentences, front-loaded with the core action and scope, with zero filler. Every clause carries information the agent needs to select and interpret 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?

There is no output schema, so the description usefully summarizes the return shape (size and last write per file) and the exclusion of code files. It is nearly complete for such a simple read tool, though it says nothing about ordering or empty-workspace behavior.

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?

With a single parameter and 100% schema description coverage, the schema already documents privateKey fully. The description adds no extra meaning about the key's format or behavior, 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?

States a specific verb and resource ("List the lambda's workspace") and adds scope details (size and last write per file). It explicitly distinguishes itself from the sibling read_lambda by stating the code lives there instead.

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?

Clearly scopes usage to "runtime files only" and routes the agent to read_lambda for code, which is effective when/when-not guidance. It doesn't enumerate other siblings like list_demos, but the key alternative is named.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by stating that the guide covers what is imported, what is refused, and platform limits and terms.

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, front-loaded sentence fragment that lists the guide's contents without unnecessary words. It is appropriately compact for a zero-argument reference tool, though the fragment style is slightly terse.

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, zero-parameter guide tool with rich annotations, the description provides enough context about what the guide covers. It does not explain the return format, but no output schema exists and the content list is sufficient for correct 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?

The tool takes zero parameters, so there are no parameter semantics to explain. The schema is fully self-contained, and the description does not need to compensate for missing parameter 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 title 'Read the platform guide' and description 'Rules for writing a lambda' together make clear that this tool returns platform documentation. It specifies the content covered (returns, imports, refusals, limits, terms), but does not explicitly distinguish itself from sibling tools like read_lambda or create_lambda.

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 states what the guide contains but never says when to call this tool, when not to, or which alternatives exist. An agent can infer it is relevant while writing a lambda, but no explicit usage guidance is provided.

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 establish read-only, idempotent, non-destructive behavior. The description goes further by disclosing the 30,000-character truncation threshold, the 1,048,576-character per-file cap, and that file overrides truncation - behavioral traits the annotations cannot 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?

The content is valuable but packed into one sprawling, hard-to-parse sentence with nested clauses ('in full when they come to at most 30,000 characters, otherwise by name and length, with file to read one'). It is front-loaded on the return shape but would benefit from breaking into discrete statements.

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 carries the return-shape burden and does so reasonably: it explains status fields, version history contents, file listing format, and truncation. A read tool with annotations covering safety is adequately covered, though the truncation mechanics remain terse.

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 schema already documents all three parameters, making 3 the baseline. The description adds only modest value, clarifying that version defaults to newest and that file returns one file in full regardless of overall size.

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 (read) and resource (lambda), then enumerates exactly what is returned: status, versions, and files. It is distinguishable from read_logs and list_files, though the enumeration is buried in a dense sentence.

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?

Gives real usage context: 'Read the history before changing what you did not write' tells the agent when to call this, and it names the sibling list_demos as the key source for demos. No explicit when-not cases, but the guidance is actionable.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing the actual content categories returned (requests, prints, errors with stack traces, traffic over hour/day), which is meaningful behavioral context for a read tool with no output 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?

Two sentences, front-loaded with what the tool surfaces before moving to when to call it. The long first sentence is dense but every clause earns its place by enumerating distinct log content. Minor cost is the slight run-on quality of the content list.

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 carries the job of describing what comes back, and it does so well via the content enumeration. Combined with a fully documented input schema and clear safety annotations, an agent has enough to call this correctly; only the sibling-relationship gap keeps it from a 5.

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% — level, limit, since, and privateKey all carry their own descriptions including defaults and cursor semantics. The description adds nothing about parameters, so the baseline 3 applies; the schema does all the work here.

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 names a specific resource (a deployed lambda's logs) and enumerates exactly what is read: recent requests and their responses, printed output, thrown errors with stack traces, and traffic volumes. It is clear what the tool does, though it never names or contrasts with the sibling read_lambda, which an agent may reasonably confuse it with.

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 clear when-to-use framing: 'Call it after deploying to see that it works, and first when something is reported broken.' That is a concrete deployment/incident context, but no alternative tool is named for adjacent needs (e.g. read_lambda for configuration), so the routing is implied rather than explicit.

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 destructiveHint=true and readOnlyHint=false but say nothing about modes, prerequisites, or side effects; the description fills exactly those gaps. It discloses the read-only mode (privateKey alone returns the current entry), the content requirements for a new entry, the condition under which the listing persists ('listed while the lambda is online'), and the expected writing style.

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?

Front-loaded with what the tool does, then the gating condition, then the read mode, then entry requirements. Reasonably tight, though the style-prescription sentence ('no marketing language, no superlatives, no exclamation marks, no emoji') is somewhat verbose relative to the functional content.

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 carries the return-value burden and does so ('returns the current entry'). All five parameters are covered, prerequisites are stated, and the destructive/online-listing behavior is clear, leaving nothing an agent needs before invoking 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?

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining parameter-combination semantics that the schema cannot express on its own (privateKey alone = read; title/description/picture required for a new entry; remove takes it off). It does not add format details for image beyond what the schema already documents.

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 stack and resource ('List a lambda on the public showcase page, change its entry, or take it off') that is unmistakably distinct from siblings like create_lambda, deploy, or write_code. An agent can identify both the resource and the three modes of operation without opening the schema.

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: 'Not part of building: only do this when the user asks for it', which clearly separates it from the build/deploy workflow siblings. It also implies mode selection ('With only privateKey it returns the current entry'), though no sibling alternative is named for the listing itself.

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 destructiveHint=true and idempotentHint=true, so safety is covered. The description adds non-obvious behavior: changes take effect immediately with no deploy, and the workspace is servable at runtime. It does not explicitly say an existing file at the path is overwritten, which would have closed the loop on the destructive hint.

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?

Front-loaded with the core action in the first sentence, then rationale and use cases. The second sentence is long and carries two ideas (deploy-free shipping, large non-code files), but both earn their place; nothing is redundant with the 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 4-parameter mutation tool with no output schema and full annotation coverage, the description explains what the tool affects and why it exists. The only omission is explicit overwrite/return behavior, a minor gap given destructiveHint already signals mutation.

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 path, content, encoding and privateKey are all documented in the schema itself. The description adds no syntax, format, or constraint details beyond the schema, so the 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 ('Write a file to the lambda's workspace') and immediately characterizes the target as a runtime directory the lambda can read, write and serve. It also distinguishes itself from the code-writing siblings by framing itself as the destination for non-code assets like front ends or large 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?

Gives clear context for when to use it ('ship a front end that changes independently of the code', 'large files that are not code'), which implicitly separates it from write_code/change_code. It stops short of naming those alternatives or stating explicit exclusions, so it is clear but not fully routing.

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 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.