Velven

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond the annotations: the sign-in gating and the interactive sign-in prompt, which an agent must anticipate before invoking.

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, the core action front-loaded before the auth caveat, with no wasted clauses. The sign-in consequence sentence is slightly wordy but carries genuine behavioral 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 no-param, read-only list tool with an output schema already defining the return shape, the description covers purpose and the one operational caveat (auth). Nothing essential is missing, though it does not describe result size or pagination.

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 no parameters, so the baseline is 4. The description's field enumeration describes output rather than input and does not conflict with the empty 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 ('List the spaces of the signed-in Velven account') and enumerates the returned fields (slug, title, status, hosting, page). It is immediately distinguishable from the sibling verbs publish, rollback, search_docs, and versions.

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 states the precondition ('Needs sign-in') and the consequence of calling without it (the app prompts the person to sign in). It does not name alternative tools or when not to use this one, but for a zero-parameter account-scoped list tool the guidance given is sufficient.

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=false, openWorld=true, idempotent=false, destructive=false, so the safety profile is covered; the description adds real behavior beyond that: safety-check gating, preview-by-default, unlisted-page/claim-token mechanics, and the 3 MB cap. It does not say what happens to the previous live version on update (though the rollback/versions siblings imply retention), which keeps it short of 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 dense sentences, front-loaded with purpose before branching on auth state. The telegraphic 'Signed in:'/'Not signed in:' fragments are efficient rather than padded, though the last sentence stacks two update paths and slightly taxes parsing.

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 14-parameter, nested-object, open-world publish tool with an output schema present, the description covers the auth/preview/live branching and file limits well. Return values are correctly left to the output schema, but the file-exclusion rules (velven.json, dotfiles, node_modules) live only in the schema text, not the prose.

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 per-field baseline is 3; the description goes further by giving cross-parameter rules the schema cannot express (prod is signed-in only, title/type/devices required only for a new space, space vs claim selecting the update path). That relational guidance is genuine added value.

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?

Opens with a specific verb+resource+target ('Publish a browser game, world, tool or wonder on Velven's hosting') and immediately bounds it ('from one HTML page or a small set of files (3 MB in all)'). It also covers the update path (space/claim), so an agent can distinguish it from siblings like versions or rollback 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?

Explicitly partitions usage: signed-in yields a private preview unless prod:true, unsigned-in yields an unlisted page and a claim token; a new space requires title/type/devices, while updates pass space (signed in) or claim (not signed in). This is exactly the when/when-not routing an agent needs, with no alternative left to inference.

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, idempotent and openWorld, so the bar is lower, yet the description adds non-obvious behavior beyond them: the target version goes live immediately without a new check, and authentication is required. It does not say what happens to the currently live version or how failures surface, so it falls short of 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 core action front-loaded, then the selection constraint and the auth prerequisite. Every clause carries information an agent needs; there is 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?

With annotations covering safety semantics and an output schema covering return values, the description only needs to supply action, constraint and prerequisite — all of which are present and precise. Nothing required to invoke the tool correctly 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 schema already documents both parameters, but the description adds a real constraint not present there: version must be one that was previously live (rollback: true). That narrows the valid domain of the version argument meaningfully beyond 'the version number to make live again.'

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: 'Make an earlier version of a hosted space live again.' It is immediately distinguishable from siblings like versions (which lists them) and publish (which creates new deployments), and the audience can identify the 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?

It states a clear precondition: only a version with rollback: true (visible via the versions sibling) can be selected, and sign-in is required. That is strong when-to-use guidance, though it never explicitly frames the inverse (what to do when the version is not rollback: true) or names the sibling to consult.

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=true and openWorldHint=false, so safety is covered by structured data. The description adds only that results are 'best matching sections with links' — useful but thin, with no detail on relevance ranking or how results behave when nothing matches.

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 verb+resource leads the sentence, followed by a compact topic inventory and the return shape. The long comma-separated topic list is information-dense but borders on a catalogue; still, every clause carries routing value.

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 an output schema present, the description need not explain return values, and it briefly signals the return shape anyway. Scope is well covered for a simple two-parameter search tool; only ranking behavior is 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 description coverage is 100%, so both query and limit are already documented in the schema, including the default of 5. The topic enumeration hints at useful query phrasing but adds no syntax or format meaning 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 (Search) and resource (Velven's documentation), then enumerates the covered topic areas (publishing, velven.json, CLI, SDK, agent API). This clearly distinguishes it from the sibling tools my_spaces, publish, rollback, and versions, which are all operations rather than documentation lookup.

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 implied by the topic list and the read-only nature of the tool, but there is no explicit statement of when to reach for this versus reading docs another way, and no exclusions. Adequate but leaves the agent to infer context.

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 mark it read-only and closed-world, but the description adds meaningful behavior: ordering (newest first), enumerates statuses, notes refused versions include a reason, indicates whether rollback can pick a version, and states auth is required. These details go well beyond the annotation hints.

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 dense sentence plus a short auth note, with the core action and ordering front-loaded. Every clause conveys 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?

For a read-only list tool with an output schema and annotations covering safety, the description sufficiently covers auth, ordering, statuses, and rollback eligibility. Nothing essential for correct invocation 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 the single 'space' parameter is documented with a slug pattern and example. The description adds no syntax or format detail beyond the schema, 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 (List) and resource (a hosted space's versions), plus ordering and scope. An agent can identify it as the version-history reader among siblings 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?

Gives a prerequisite ('Needs sign-in') but does not say when to choose this over sibling tools such as rollback or publish. Usage is implied by the listing purpose, but there is no explicit when/when-not guidance.

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