GenHTTP Lambda

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

Annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) leave the destructive flag unexplained, and the description fills that gap well: counting is off until enabled, nothing is counted beforehand, enabling starts from the next request, and switching off deletes the collected data. It also discloses UTC day bucketing, a few-minute write cadence, and tier-based retention (7 days free, a year premium). It stops short of clarifying whether this tool itself can delete anything, leaving a small ambiguity against 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 payload is real and front-loaded, but the first sentence is a long comma-chained list and the cadence/UTC/retention details are crammed into a second dense sentence. Structure is serviceable rather than clean; several clauses could be tightened without losing 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 carries the burden of describing what comes back, and it does so thoroughly, including granularity, retention and the enable lifecycle. The only residual gap is the exact relationship between the tool's destructiveHint and the fact that disabling happens elsewhere.

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 still adds value by tying the default day count to the tier ceiling and by restricting enable to an explicit user request. The privateKey is not discussed, but the schema covers it 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 opening sentence names the resource and enumerates exactly what is returned: visitors, pages opened, requests per day, plus referrers, countries, devices, browsers, OS and crawlers. It is a read tool for site analytics, clearly distinct from read_logs or read_database in substance, although no sibling is named to make the distinction explicit.

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?

"Use it to answer what the user asks about their visitors, or to see which pages matter before changing them" gives concrete usage contexts, and the enable guidance is conditional and explicit ("only when the user asks"). It also warns that disabling is not this tool's job but the owner's in the editor. No sibling comparison is offered, which keeps it from 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 destructive=true and non-idempotent; the description adds substantive behavior on top: unchanged files are preserved, uncompilable code is saved but never published, check compiles without putting anything online, and feature edits leave the live lambda untouched. Those are exactly the side-effect details an agent needs before a destructive write.

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?

Dense and front-loaded: the core verb and scope come first, then workflow, then the compile/safety caveat. A few clauses are telegraphic ('deploy: true to try it at the feature's preview address, merge_feature when it is right'), costing some readability, but no sentence is 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 9-parameter destructive mutation with no output schema, the description covers the major risk and workflow questions (what is preserved, what gets published, feature vs version, compile checking). What it does not say is what the call returns on success (version id? diagnostics only when check is true?), which matters given no output schema is declared.

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 goes beyond the schema by explaining the interplay between 'feature', 'deploy', 'merge_feature', and 'check' — semantics the per-parameter descriptions state only in isolation. It does not clarify 'change' vs 'specification' or the edits/remove ordering beyond what the schema already says.

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 plus an enumeration of the three capabilities (add/replace files, remove files, in-file text replacement), which lets an agent distinguish this composite edit tool from single-purpose siblings like write_code, delete_file, and upload_file. The 'everything not named stays as it is' clause further pins down the semantics of the operation.

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 an explicit workflow: use 'feature' to iterate on an existing lambda, 'deploy: true' to try it at the preview address, 'merge_feature' when it is right; without 'feature' the newest version is changed and saved as a new version. It also states an in-context obligation (update docs/ and tests/ in the same change) and explains the check-only path, so an agent knows not only when to call it but how to sequence calls around it.

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 that this is a safe, read-only, idempotent operation, and the description adds useful behavioral detail beyond them: it returns file/line diagnostics and does not build the handler, so deploy can still reject some routes. That limitation is important context. It does not cover auth expectations or diagnostic format in depth, but it goes meaningfully beyond 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?

Two tight sentences, front-loaded with the core action and scope, followed by the one limitation that matters. 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 compile-check tool with no output schema, the description covers purpose, side-effect scope, return shape at a high level, and a key limitation. It could say a bit more about diagnostic structure or success behavior, but it is complete enough to call 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%, and the schema itself richly explains 'files' and 'privateKey'. The description adds no parameter-specific meaning, so 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 specific verb and resource ('Compile') and immediately scopes it as a dry run ('without saving or deploying'), which separates it from write_code and deploy. It also says what it returns ('diagnostics with file and line'), so an agent can identify the tool 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' gives clear usage context: use this to validate code before persisting or deploying. It does not explicitly name alternatives or state when not to use it, but the intended role 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?

Beyond the annotations, the description discloses important behavior: the feature branches from a version, copies files and lambda data, gets its own address, and leaves the live lambda serving visitors throughout. This makes the non-destructive, state-creating nature of the operation explicit and is consistent with destructiveHint=false and idempotentHint=false.

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 concept and organized as a workflow, with no obvious filler. It is somewhat long for a four-parameter tool, but the length is largely earned by explaining the branching model and subsequent workflow.

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 create/branch/deploy/merge workflow with no output schema, the description gives a complete mental model of what is created and how to proceed. It does not describe the exact return shape, such as whether the preview address or feature identifier is returned, which leaves a minor gap.

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 four parameters are already documented in detail. The description contextualizes 'base' by explaining that the feature branches off a version and defaults to the newest, but it mostly restates schema-level meaning rather than adding substantial new parameter guidance.

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 and resource ('Start a feature') and immediately explains the concrete outcome: an isolated place to change a lambda without affecting what is online. It distinguishes the tool from create_lambda, change_code, deploy, and merge_feature by describing the branching model and preview address.

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 clearly states when to use the tool ('a place to change a lambda without touching what it has online') and names downstream tools for the workflow: change_code/write_code for editing, deploy for preview publishing, and merge_feature for completion. It does not explicitly state when not to use it or contrast it with update_feature/delete_feature, but the 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 already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description adds genuinely important context: the returned editor key is "the only way back in" (non-recoverable credential), and the lambda is not live until deploy. That is real operational disclosure 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?

Four short sentences, front-loaded with the verb and the return value, then the initial state, then the deployment caveat. No filler and nothing an agent must skip past to find the essentials.

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 explains what is returned (public address, private editor key) and the post-creation state. It doesn't mention the mandatory acceptTerms gate, though the schema covers it, leaving only a minor gap for a creation 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 coverage is 100%, so all four parameters, including the acceptTerms requirement and the view enum rationale, are already documented in the schema. The description only echoes the template parameter ("an empty starter, or a copy of a demo") without adding syntax or defaults, so 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?

Specific verb+resource ("Create a lambda") followed immediately by what the caller gets back: a public address and a private editor key. It doesn't explicitly contrast with siblings like create_feature or deploy, but the initial-state sentence ("starts with version 1 - an empty starter, or a copy of a demo") makes the tool's scope unmistakable.

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?

"Nothing is online until deploy" implicitly routes the agent to the deploy sibling for going live, and the schema's template description points at list_demos. But the description itself states no explicit when-to-use or when-not-to-use conditions, so guidance is implied rather than declared.

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; the description adds real value beyond that by detailing the destruction scope (files, preview, data copy) and explicitly excluding the lambda. It does not mention irreversibility or confirmation requirements, which would have made it a 5.

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; the scope of destruction is front-loaded and each sentence carries distinct information (what is deleted, what is spared, when to use it). 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 destructive tool with no output schema and full annotation coverage, the description is nearly sufficient: it clarifies destruction scope, the lambda carve-out, and intent. Only a note on irreversibility or required authorization 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% for both parameters ('The feature.', 'The editor key.'), so the schema carries parameter semantics. The description adds no format or selection guidance for 'feature' or 'privateKey', leaving the baseline 3 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 gives a concrete verb ('throw a feature away') and enumerates exactly what is removed: files, preview, and the data copy. It also states a boundary ('the lambda is not touched'), which helps distinguish it from delete_file and delete_lambda-style operations, though it never names a sibling 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?

The phrase 'For a feature the user does not want after all' implies the use case but states no alternatives, prerequisites, or exclusions. It gives a soft when-to-use signal while leaving the agent to infer how this differs from delete_file.

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. The description adds genuinely new behavioral context beyond them: the deletion is permanent ('No deploy or rollback brings it back') and workspace data is shared across every version. It does not discuss permissions or rate limits, but the editor-key auth is documented in 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 compact sentences, zero waste, with the destructive scope and permanence front-loaded ahead of the optional feature behavior. Every clause carries information the agent needs.

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 destructive, non-read-only tool with no output schema, the description covers scope, permanence, and the feature override, and annotations cover safety and idempotency. What is missing is minor: no statement of required permissions beyond the schema's editor key, and no note on folder-recursion behavior beyond 'with its contents'.

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 all three parameters are already documented. The description reinforces the meaning of `feature` (delete from that feature's copy) and clarifies that `path` is relative to a workspace shared by all versions, but adds no format or syntax detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 (a file, or a folder with its contents) plus the exact scope: the workspace / lambda's data, shared by every version. An agent can distinguish this from upload_file, list_files, or delete_feature without opening any 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?

Gives an explicit routing condition: 'With feature, from that feature's copy instead,' which tells the agent when the optional parameter changes the target. It stops short of naming sibling alternatives or stating when-not to use it (e.g. prefer delete_feature for features), so it is clear context without full exclusions.

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. The description adds a consequence annotations cannot express: readers using Secret.Read will fail from their next call onward, which is meaningful impact context.

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?

Highly economical and front-loaded: consequence of deletion is stated before the usage caveat. Some sentences are telegraphic fragments ('With feature, from that feature's copy instead'), which slightly hurts readability.

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 destructive tool with no output schema, the description covers the effect on readers, the usage constraint, and the feature-copy option, which is enough to call it correctly. It omits auth/permission detail, though the schema supplies the editor key.

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 name, feature, and privateKey are all documented in the schema. The description adds only a light gloss on 'feature' ('from that feature's copy instead'), matching the schema text rather than extending it, so 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 ('Remove a secret') and immediately qualifies scope with the feature-copy variant. It does not name sibling tools like set_secret or delete_feature to route between them, 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?

Explicitly constrains when to use it ('Only when the user asks for it, or a secret you stored yourself is no longer used'), which is real use/when-not guidance rarely seen. It does not name an alternative tool, only the feature-parameter variant.

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 destructive=true and idempotent=true, so the safety profile is partly covered. The description adds genuinely non-obvious behavior: failed deploys return diagnostics and 'whatever was online stays online', and feature deploys run against their own copy of the data without touching the lambda. It omits any mention of key/permission requirements or what a successful return looks like.

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 primary version-deploy case before the feature variant. The em-dash asides are slightly dense but every clause carries information; nothing is padding.

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, and the description fills the gap by noting diagnostics are returned on failure and the prior state is preserved. For a destructive two-mode tool this is close to sufficient; only preconditions and a hint at the success return shape are 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 coverage is 100%, so all three parameters are already documented, including the version default and the feature override. The description's param-level content ('newest by default', feature deploys to a preview address) largely restates 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 (deploy/publish) and its two distinct scopes: a saved version to its public address, or a feature to its own preview address. An agent can tell exactly what the tool acts on. It stops just short of a 5 because it never names or rules out any sibling tool as an alternative route.

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 'With feature, deploy...' clause gives clear conditional guidance for choosing between the two modes, and 'the newest by default' tells the agent it can omit version. There is no explicit when-not-to-use or prerequisite guidance (e.g. what must exist before deploying).

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?

Goes well beyond annotations: immediate effect without deploy, lambda restart on next request so migrations run, database initially empty, and no off tool because disabling deletes data. Minor gap: it does not explicitly reconcile the destructiveHint with the enabling action or discuss failure/auth behavior.

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-loads the three kinds and then follows with when-to-use and operational consequences; every sentence adds value. The first sentence is dense with parentheticals, which slightly hurts scanability.

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?

Covers the key behavioral context an agent needs for a mutation tool: effect timing, restart/migration side effect, initial state, and why no disable tool exists. It leaves return/response and authentication expectations unstated, but annotations and the fully covered schema fill most of that.

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 both parameters are documented, and the description adds meaningful semantics for the 'kind' enum by explaining each option's state and purpose. It adds nothing for privateKey beyond the schema's 'editor key,' so not 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?

States a specific verb-resource pair ('Switch on a kind of data') and enumerates the three data kinds with their initial states. It distinguishes the operation from sibling read/write tools by framing it as enabling lambda data and notes that no disable tool exists.

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 concrete conditions ('when what you build needs it') with examples (records need database, API key needs secrets) and explicitly routes disabling to the owner/editor. This tells the agent when to call it and prevents it from searching for an off-tool.

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 given. The description adds real context beyond that – demo keys are public and read only, so no auth or permission concerns – but says nothing about the size or shape of the returned list or how entries are identified beyond "id" being usable as a template.

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 demos are, then the read-only nature, then the next-step tooling. Every clause carries information, though the enumerated build examples are slightly longer than needed for an agent that only needs to choose 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?

No output schema exists, and the description partially compensates by implying entries carry ids usable as create_lambda templates and are publicly readable. It does not state what fields each entry exposes (name, description, id), which is the one thing an agent calling this blind would still want.

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?

Zero parameters, so there is nothing for the description to disambiguate; the baseline is 4. The description correctly describes a no-argument index call without inventing filtering options the schema does not support.

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 ("Demos this platform keeps online") and immediately qualifies what a demo is: a finished lambda showing one way to build something, with concrete examples (REST API, login, websocket game, uploads, live updates). This clearly separates it from siblings like list_files or read_lambda, which return files or code rather than an index of example 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?

Gives explicit follow-up routing: read the closest demo with read_lambda (plus list_files, read_logs) before writing similar code, and start from a copy via create_lambda using a demo's id as template. That is a genuine when/how workflow rather than vague context. It stops short of an explicit when-not or exclusion condition, so it is not a full 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 readOnly, idempotent, non-destructive, and non-open-world. Beyond that, the description discloses return content (file names with size and last write, workspace switched-on state) and a stability property ('the same whichever version is online'), which is genuine behavioral context not present in 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 main purpose is front-loaded, which is good, but the terse dash-heavy phrasing ('the same whichever version is online', 'With feature, that feature's copy of it') is awkward and requires re-reading. It is compact but sacrifices clarity for brevity.

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 by describing files plus metadata and workspace state. Annotations already cover the safety profile. It lacks any note on pagination or result limits, which is the only notable gap for a list 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 schema already documents both parameters, establishing a baseline of 3. The description adds only marginal meaning by noting that feature yields 'that feature's copy of the data', which essentially restates the schema's own wording.

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 (list) and resource (the lambda's data), and enumerates what that data contains: workspace on/off state plus every file with size and last write. It explicitly contrasts with read_lambda ('the code and resources of a version are in read_lambda'), so an agent can distinguish it from the nearest sibling. The only weakness is that the name list_files undersells the workspace-state content, adding mild ambiguity.

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 routes the agent away from this tool for code/resources by naming read_lambda as the alternative, and clarifies the feature-scoped variant. That is clear contextual guidance, though it stops short of explicit 'use this when...' phrasing or exclusions for the other data-adjacent siblings.

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, closed-world), so the bar is lower, and the description still adds real value by disclosing what the listing reports: enabled state, stored value/timestamp, 'missing' names read via Secret.Read, and 'optional' names checked via Secret.Exists. That category breakdown is meaningful behavior beyond 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?

It is a single front-loaded sentence with no filler, but the heavy dash-and-parenthetical construction makes it dense and hard to parse on a first read, and the nesting of two categories (missing/optional) inside the run-on sentence costs clarity.

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 correctly carries the return-value burden by enumerating the status categories returned. Combined with complete annotation coverage and fully described parameters, an agent has enough to call it correctly; only the absence of any write-scenario routing keeps it short of 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%, so the baseline is 3. The description's 'With feature, that feature's copy' loosely reinforces the schema's own 'List this feature's copy instead,' but adds no syntax, default, or format detail beyond it, and says nothing about the required privateKey.

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 ('list the lambda's secrets') and immediately scopes the output ('by name - never their values'), which cleanly separates it from value-returning or mutating siblings. However, it never names the relevant siblings (set_secret, delete_secret), so the differentiation is inferred rather than explicit.

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?

Usage is only implied: an agent can infer you'd call this to inspect secret state, and 'With feature, that feature's copy' hints at the feature-scoping use case. There is no explicit when/when-not guidance and no routing to set_secret or delete_secret for write operations.

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?

Goes well beyond the destructiveHint annotation by specifying exactly what is destroyed (the feature, its preview, and its copy of the data) and what is preserved (the lambda's own data). It discloses blocking conditions and the immediate-vs-deferred deployment consequence.

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 and its destructive effects, then preconditions, then the deploy option. Dense but nearly every clause carries operational information; the final deploy sentence is slightly redundant with the schema property description.

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 covers the necessary ground: destruction scope, data preservation, gating refusals, prerequisite steps, and deployment timing. An agent has everything needed to call this destructive merge safely.

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 real meaning for deploy, clarifying that true publishes immediately while false defers going live until the user wants it. It also explains that change/specification default to the feature's values, though that is largely echoed in the 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?

States a specific verb and resource ('Make a feature's files the next version of the lambda') plus the consequential side effects (feature, preview and its data copy deleted). It is clearly distinguishable from the sibling update_feature, which it names explicitly for the different job of rebasing.

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 preconditions and refusals: refused while the feature is not based on the newest version (routes to update_feature) and while its code does not compile. It also tells the agent to bring docs/tests up to date and run tests against the preview before merging, and when to set deploy:true versus deploying later.

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 and idempotentHint=true, but the description goes well beyond them: it discloses the precise blast radius ('every version's code, resources, documentation and tests, and the history'), what is explicitly NOT published (database, workspace, secret values), that previously-private historical versions become public, and that removal preserves stars. That's exactly the context an agent needs before triggering an irreversible disclosure.

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 action and destination, and every sentence carries unique information — the data exclusion, the opt-in rule, the license question, the status mode, and the privacy warning. It is dense and tightly packed into one paragraph, which costs a little scannability, but there is essentially 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?

No output schema exists, and the description compensates by specifying the privateKey-only return ('whether it is published'). Combined with the publicity warning about keys, passwords and personal data, an agent has everything needed to call this safely and correctly, including the consequence of the destructive path.

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 meaning the schema does not: the license default (MIT on first publish), the author fallback ('the authors of' the lambda), and the privateKey-only status-query mode. It does not re-explain remove/author syntax, which the schema already handles well.

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 ('Publish a lambda's source code') plus the exact destination path '/source/{publicKey}', and immediately enumerates the accompanying actions (star, download as .NET project, change license, take down). No sibling tool in the list publishes source, so there's no ambiguity with deploy, showcase or read_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?

Explicit when-to-use and when-not-to: 'Not part of building: only do this when the user asks for it, and ask which license if they did not say (MIT unless they want another).' It also defines a distinct invocation mode ('With only privateKey it returns whether it is published'), which tells the agent this tool doubles as a status check.

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, openWorldHint=false and destructiveHint=false, so safety and side-effect behavior is covered. The description adds the substantive trait of what content is inside, but says nothing about the return format, size, or whether the whole guide comes back at once — relevant for a no-arg documentation 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?

A single sentence, front-loaded with the highest-value clause ("How this platform works - read it first") followed by a content inventory. The topic list is dense but every item names a distinct concept, so it earns its length; a bulleted structure would read more easily but the compression is defensible.

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 zero parameters, rich safety annotations and no output schema, the description's job is basically to say what the guide contains and why to start here — both are done. The only gap is the shape of the response (guide text vs. structured sections) and how it relates to the many operational siblings beyond the "read first" nudge.

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 is nothing for the description to disambiguate; the baseline of 4 applies. The schema correctly declares an empty object with additionalProperties=false, matching the argument-free usage the description implies.

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 establishes the resource ("how this platform works" / the platform guide) and enumerates the conceptual topics it covers: versions, features, data lifetimes, code vs. resource, docs/tests, imports, refusals, limits, terms. It is clearly distinct from the operational siblings (deploy, create_feature, read_logs, etc.), but it never states plainly that it returns documentation text, relying on the title verb "Read" for the action.

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?

"read it first" is an explicit sequencing directive that tells the agent to consult this before the operational siblings — strong, actionable guidance. It stops short of explaining when-not to use it (e.g., once the agent already knows the model) or which sibling to go to after reading.

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 non-destructive, so the safety profile is known; the description nonetheless reinforces it and adds value beyond the annotations by explaining that writes happen inside the lambda via Database.GetConnection(), that rows come back newest-first, and that pages cap at 100. It stops short of describing the shape of the listing response or what 'switched on' and 'how full it is' concretely mean.

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?

There is little waste, but the first sentence is a long, comma-spliced run-on ('its records, shared by every version: whether it is switched on, how full it is, and its tables and views with their columns and how many rows each holds') that is harder to parse than the content warrants. The information is front-loaded, but the structure could be broken up for faster scanning.

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 no output schema and seven fully documented parameters, the description covers both modes (schema listing and paged row reading), the feature-scoped variant, page size, and ordering. An agent has enough to call it correctly without further 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 3, but the description adds cross-parameter meaning the schema cannot: 'table' plus 'limit'/'offset' produces a page of that table's rows newest-first, capped at 100, and 'feature' swaps in a feature-scoped copy. That interaction between parameters is genuinely extra information, though ordering via 'order'/'ascending' is left to the 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 names a concrete resource (the lambda's database, its tables, views, columns and row counts) and a concrete mode switch (with table, a page of that table's rows). It is more specific than the bare verb+resource, but the opening is a dense noun phrase rather than a clean 'Read X' statement, and it never distinguishes itself from siblings like read_lambda or analytics.

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?

'Use it to see that migrations were applied and records were written' gives a real usage cue for the listing mode. There is, however, no guidance on when not to use it, no mention of the sibling tools (analytics, read_lambda, enable_data) that might read the same data, and no note that privateKey/auth is required to get anything back.

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 read-only annotations, the description discloses important behavior: documentation is returned first up to 20,000 characters, files are returned in a specific order while fitting into 30,000 characters, and `file` can return up to 1,048,576 characters before falling back to a zip. It also explains what data is exposed, including secrets that have no value yet, and what feature reads include, such as newer versions to merge.

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 dense and largely front-loaded around what is read, but it is delivered as one very long paragraph with semicolon-separated clauses. Most details earn their place for a complex read tool, but the lack of structure makes it harder to scan than it should be.

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 carries the burden of explaining return contents and does so thoroughly: status, features, versions, data, secrets, documentation, tests, files, truncation limits, ordering, and feature merge context. For this tool's complexity, an agent has enough information 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 coverage is 100%, so the baseline is 3, but the description adds meaningful parameter context: `feature` switches from version reading to feature reading, `file` returns a single file in full including tests and resources, and demo usage requires a key from `list_demos`. It reinforces the schema rather than merely repeating it.

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: it reads a lambda's status, open features, recent versions, data, and a selected version or feature with documentation, tests, and files. It clearly distinguishes modes via the `feature` and `file` parameters and mentions `list_demos` for demo keys, so an agent can tell what this tool does versus narrower 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 gives clear usage context, especially 'Read the documentation and the history before changing what you did not write,' and explains that `feature` reads a feature instead of a version and `file` reads one file. It also notes demo keys come from `list_demos`. It stops short of explicitly saying when to use this tool instead of alternatives like `list_files`, `read_database`, or `read_logs`.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value by disclosing the content shape (requests/answers, prints, error stack traces, traffic over the last hour and day) and that feature-preview activity is kept separate from the lambda's visitors. It does not discuss retention beyond the stated windows or cursor semantics, which are covered in 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?

Front-loaded with the content inventory, followed by the feature-mode clarification and then the usage guidance. Dense but every clause carries information; the long enumeration of what is returned is justified because no output schema exists.

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 must convey return contents — it does so well (requests, prints, stack traces, traffic windows), and the cursor/limit/level mechanics live in the fully documented schema. The only gap is not stating how level, limit, and time windows interact in the response, but nothing essential for a correct call 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for the `feature` parameter by clarifying that preview activity is 'kept apart from the lambda's visitors' — isolation semantics the schema's one-liner doesn't convey. The other parameters are left to their already-thorough schema 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 (read a deployed lambda's logs) and enumerates exactly what is returned: recent requests and their answers, printed output, errors with stack traces, and hourly/daily traffic. It also distinguishes the alternate mode (feature preview logs kept apart from the lambda's visitors), which separates it from read_lambda (config) and analytics (traffic 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?

Gives two concrete usage moments: 'after deploying to see that it works' and 'first when something is reported broken,' which tells the agent it is a diagnostic entry point. It does not explicitly name alternatives like analytics or read_lambda, so routing is implied rather than spelled out.

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?

Goes well beyond the annotations: the value is sealed and never readable back, only the lambda reads it starting from its next call, no deploy is required, secrets must be enabled first via enable_data, feature scoping writes to a feature's copy, and there is a 100-secret / 32 KB quota. This is exactly the kind of operational detail annotations cannot carry.

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?

Dense but front-loaded: the primary action and its contract come first, then caveats and quota. The feature/sandbox sentence is slightly telegraphic ('With feature, into that feature's copy'), but overall each 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?

No output schema exists, and the description compensates by stating that the value cannot be read back, implying a write-only acknowledgement. Prerequisites, scoping, and limits are all covered; only the exact success/failure response shape is left implicit.

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 carries the baseline, but the description still adds meaning: it explains why the name matters (read via Secret.Read("NAME")), that feature stores a sandbox copy for trying things out, and that the value is the user-supplied one. Modest but genuine value beyond the 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?

States a specific verb and resource ('Store a secret') plus the exact code-level contract (Secret.Read("NAME")), and it is trivially distinguishable from delete_secret and list_secrets in the sibling set. An agent knows what this tool does 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-to-use: 'Only set a value the user gave you for this: when you do not have it, write the code with Secret.Read and tell the user to set it under Data > Secrets'. It also names the relevant alternatives (read_lambda, list_secrets) and the prerequisite (enable_data).

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 and idempotentHint=true; the description adds real context on top: the entry is listed only while the lambda is online, omitting image preserves the current one, and a remove flag is the takedown path. It does not spell out what happens to the listing when the lambda goes offline or whether removal is reversible, which keeps it at 4 rather than 5.

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?

Mutate/read/remove behavior is front-loaded in the first two sentences. The closing style guidance on tone runs slightly long, but it materially shapes the generated title and description, so it earns its space.

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, and the description covers the one return case it can ('returns the current entry'), plus the prerequisites. It lacks detail on the shape of that returned entry or on what the showcase listing looks like, which is a minor gap for a mutation 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 coverage is 100%, so the baseline is 3, but the description adds conditional logic the schema cannot express: a new entry requires title, description and picture, while omitting image keeps the existing one. The editorial style constraints also clarify what content the title/description fields expect.

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 names a specific verb set (list, change, take off) against a specific resource (public showcase page), so an agent can tell it apart from open_source or deploy without opening the schema. The clause 'Not part of building' further separates it from the code/deploy 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 gives an explicit exclusion ('only do this when the user asks for it') and a clear read-mode condition ('With only privateKey it returns the current entry'). It does not name a competing sibling (e.g. open_source) as an alternative, so it stops short of full 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?

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds a caveat those annotations cannot express — that no validation occurs that the newer changes are actually present, so correctness is the caller's responsibility. It does not explain what the destructive hint means concretely (e.g. whether the previous name/change text is overwritten), which keeps it below 5.

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, no filler, with the action list front-loaded. The middle sentence is long and its clauses are chained awkwardly, but every sentence carries 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?

No output schema and six parameters mean the description must carry the load; it handles the base-move workflow well but leaves the metadata-editing half (name, change, specification, required feature/privateKey) unaddressed and never spells out the consequence of the destructive hint.

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 all six parameters are already documented in the schema. The description adds sequencing meaning for base ('once that version's changes are in its files') but nothing for change vs. specification, which remain the least obvious pair in the 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?

Specific verb+resource: rename a feature, edit its description text, or move its base. The mention of merge_feature in the same breath distinguishes it from that sibling, though 'change what it says about itself' is a vague gloss for the change/specification fields and never names them.

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 an explicit routing rule for the base-move case: merge_feature refuses a feature not based on the newest version, so bring the newer changes in first and then move base here. That is real when-to-use guidance with a named alternative, but nothing is said about when to use this for name or note changes versus leaving the feature alone.

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 and readOnlyHint=false, so the safety profile is carried structurally. The description adds real context beyond that: the change only alters the default and does not lock anyone in, which materially reframes the 'destructive' hint as low-blast-radius. It omits permission/auth requirements and confirmation behavior, keeping it out of 5 territory.

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 purpose is front-loaded in the first clause, but the rest is a long run-on with em-dash asides and elliptical phrasing ('and Full every section, the code, files...'), which takes effort to parse. Most sentences carry useful content, but the structure is muddled rather than crisp.

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 only two fully-required, fully-documented parameters and no output schema, the description covers purpose, scope of effect, and when to invoke, which is most of what an agent needs. It leaves auth/permission prerequisites and any confirmation or return signal unstated, a minor gap for this complexity level.

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% and the 'view' enum already documents both values in detail, so the description's prose about 'Simple' vs 'Full' largely restates structured data. The added nuance ('for an owner who does not write code') is marginal, and 'privateKey' is not explained at all beyond the schema's 'The editor key.' 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?

The description states a specific verb and resource ('Change how a lambda's editor opens') and enumerates the two view modes, so the agent knows exactly what is being modified. It does not differentiate against siblings like update_feature or change_code, but the scope (editor view default) is unambiguous 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?

It gives an explicit gate ('Only do this when the user asks for it') and an explicit reason not to act preemptively ('whoever opens the editor can switch for themselves, and that choice stays theirs'), which is a genuine when-not condition. It stops short of naming alternative tools, but no sibling covers this action.

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 real behavioral context beyond the annotations: changes take effect immediately without a deploy, and the data survives deploys, rollbacks and merges. It also clarifies that the feature variant avoids mutating the real copy. It does not state what happens to an existing file at the same path (overwrite vs. version), which is the one gap relative to 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?

Front-loaded with the core action in the opening clause, and the remaining sentences each carry routing or behavioral information. The prose is dense and dash-heavy, slightly longer than needed, but no sentence is 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?

With no output schema, annotations covering safety flags, and full schema coverage for five parameters, the description supplies the missing pieces: persistence semantics, immediacy, and tool selection. Only overwrite behavior and any size limits are left unspecified.

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 still adds semantic meaning the schema lacks: it explains the workspace-relative root and that the feature parameter redirects the write to an isolated copy, framing the parameter's intent rather than just restating it.

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 concrete verb+resource ('Write a file to the lambda's workspace') and immediately scopes it to shared, deploy-independent data. It also names what it is NOT for (front-end pages/scripts/styles, database records), so an agent can separate it from write_code and database tools without opening schemas.

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 (runtime assets like images, and large non-program inputs such as models, datasets, media) and when-not (front-end code belongs in the version's resources via write_code; records belong in the database). The feature parameter's purpose is also explained as a scratch copy for experimentation.

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, so the bar for added context is lower — yet the description goes well beyond them: it states the previous set is replaced wholesale, that files under resources/ are served at runtime while other files are only kept, that runtime data belongs in the database/workspace rather than here, and that deploy publishes immediately. This is substantial behavioral disclosure for a destructive write 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 runs several hundred words as one unbroken block, much of it platform documentation rather than tool behavior — Entity Framework Core DbContext usage, Evolve migration placement, what tests/README.md represents, how front-end assets are laid out. These belong in platform_guide, which is a sibling tool. The first sentence is front-loaded, but the body does not earn its length.

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 destructive, multi-file save with 7 parameters and no output schema, the description covers what an agent must know before calling: what is replaced, where files land (compiled vs served vs stored), how feature and deploy change the outcome. Only error behavior and response expectations are unaddressed, which is acceptable given no output schema is declared.

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 still adds meaning: 'feature' is framed as saving into an existing feature without touching the lambda or its online state, 'deploy' is tied to which address receives the publish, and 'change'/'specification' are given intent ('say why with specification and change'). It stops short of covering failure modes or size limits, but the added semantics are real.

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 specific verb and scope: 'Save every file, replacing the previous set: as a new version of the lambda, or - with feature - into that feature.' It distinguishes the version path from the feature path and names the sibling it is not ('use change_code' for incremental saves). The core purpose is clear, though it arrives wrapped in a large conceptual essay that dilutes the signal.

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 is present: 'To send only what changes, use change_code' and 'To change a lambda that is already in use, work in a feature.' It also states what deploy: true does in-call (publishes to public vs preview address), so the agent knows both when to use this tool and when a sibling is the right call.

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