list_versions

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

With no annotations provided, the description carries the behavioral disclosure burden. 'Lists' signals a read-only operation, and the description adds that versions are immutable snapshots and that the return value is a formatted string. It does not, however, disclose sorting, pagination, failure behavior, or authentication prerequisites, so transparency is adequate but not rich.

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 well-structured with a front-loaded purpose, a concise explanatory sentence, an Args section, and a Returns section. The only blemish is the inclusion of 'service' in Args when the schema does not list it, and the return statement is somewhat redundant given an output schema exists, but overall there is no wasted prose.

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 low-complexity read-only listing tool, the description covers the main purpose, key inputs, and basic return type. It is missing guidance on auth dependencies, empty version lists, ordering, and how it differs from list_deployments, and the 'service' parameter mismatch adds a small completeness gap. It is sufficient for a basic invocation but not fully self-contained.

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 0%, so the description must compensate. It gives one-line meanings for 'user_google_email' and 'script_id', but these largely restate what the parameter names already imply. It also mentions 'service: Injected Google API service client,' which is not in the input schema and could create minor confusion, though the word 'injected' signals it is not caller-supplied.

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

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

The description opens with a specific verb and resource: 'Lists all versions of a script project.' It clearly names the object type (versions), the scope (all versions), and the target resource (a script project), which separates it from related siblings like get_version, create_version, and list_deployments.

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 implies when this is useful by explaining that versions are immutable snapshots created at deploy/version-creation time, so an agent can infer it is the right tool for viewing version history. However, it does not explicitly say when not to use it or name alternatives such as get_version or list_deployments, leaving usage boundaries implicit.

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