reachpad-mcp

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

The description adds meaningful behavior beyond the annotations: the original is untouched, the fork is based on the last sealed snapshot, and the cost is only a delta rather than a full rebuild. These facts are not visible in the schema or annotations and are important for correct usage.

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, all substantive. The core action comes first, followed by the non-destructiveness guarantee and then a helpful cost framing. No filler or repetition of schema content.

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

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

For a two-parameter tool with no output schema, the description is largely sufficient: it states what the input does, what the original workspace incurs, and why the operation is useful. Minor gaps remain around what the tool returns and behavior for workspaces without a sealed snapshot, but these do not block invocation.

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

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

With only 50% schema description coverage, the description partially compensates by implying that 'workspace' is the source sealed workspace and that 'name' names the new fork. However, it does not explain whether 'name' is optional in naming behavior, what happens if omitted, or other constraints on the workspace parameter.

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 specific language: 'Fork a workspace from its last sealed snapshot into a new one.' It clearly identifies the resource, the action, and what is produced. The phrase 'original is untouched' also distinguishes it from operations that modify the source workspace.

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 explains the intended use case: trying several approaches from one prepared state using a cheap fork. This is clear contextual guidance even though it does not explicitly name an alternative like create_workspace or state when not to use the 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?

The annotations already indicate a mutating, non-idempotent operation, but the description adds meaningful behavior beyond that: persistence, process survival across calls, and optional git cloning. It also discloses the workspace id return value, which is not available from the schema or 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?

Three sentences, each with a clear job: define the resource, mention the optional clone behavior, and explain the return value. No filler, no redundancy, and key details are front-loaded.

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?

Given only three optional, fully documented parameters and no output schema, the description provides what an agent needs: what is created, why the workspace persists, and what the caller should do with the result. Cleanup and lifecycle are covered adequately by the sibling tool set.

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 all parameters are optional, so the schema already documents the parameter semantics. The description adds only a light confirmation that repository cloning is optional, but does not provide additional parameter-level context or conventions 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 action and resource: create a persistent development workspace, and defines what that means: a filesystem and processes that survive between calls. It also explains the return value and how it relates to every other tool, which separates it clearly from the get/list/pause/delete 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?

Clearly implies when to use it: when a long-lived workspace is needed, and it contrasts with sibling verbs like list, get, pause, and delete. It does not explicitly name an alternative or provide when-not-to-use phrasing, but the persistence context is strong enough for an agent to select it correctly.

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 reveals that the operation is not data-destructive, that snapshots/history survive, that the workspace stops counting as live and can no longer be used, and that a running workspace will be refused with `lease_held`. This meaningfully informs the agent of the mutation's real-world effects without contradicting 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 description is compact and front-loaded: the first sentence states exact action and outcome, the second clarifies non-destructiveness, and the third handles the critical precondition. Every sentence provides necessary guidance, with 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?

The description is comprehensive for a one-parameter, no-output mutation tool: it explains effect, survival of data, preconditions, and failure behavior. The only notable gap is identifying the `workspace` parameter's format, which is partially penalized under parameter semantics but prevents a perfect score here.

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

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

Schema description coverage is 0%, so the description needs to compensate for the single `workspace` parameter. It does not clarify whether `workspace` is an ID, name, object reference, or how it should be obtained (e.g., from list_workspaces/get_workspace). The only inference is that it identifies the workspace to archive.

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 ('Archive') and resource ('workspace'), and clearly states the core effect: freeing the plan slot while keeping snapshots and history. It explicitly disambiguates itself from deletion, which is critical given the tool name 'delete_workspace', and sets it apart from sibling tools.

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 clearly explains when to use this tool: to free a plan slot without destroying data. It also gives an explicit when-not: a RUNNING workspace cannot be archived, and it names the required action in that case ('pause_workspace first') along with the refusal error (`lease_held`).

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

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

The description explains the idempotent behavior concretely — re-running returns the link the port already has — going beyond the idempotentHint annotation. It also communicates that the result is an externally reachable link, matching openWorldHint. No contradiction with 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?

Three sentences, each earning its place: the core operation, the purpose, and the idempotent behavior. The most useful operational detail comes first, and the prose is tight.

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 straightforward exposure operation with no output schema, the description supplies the missing output concept ('a link that reaches it') and the idempotent consequence. It does not dwell on what happens to the link later, but that is adequately covered by the idempotence and the revoke_port sibling.

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 schema already documents port and check in detail, and the description reinforces the general 'inside a workspace' context. However, the description adds little for the undescriabed workspace parameter, and the schema coverage is 67%, not high enough for the description to be merely decorative.

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 clearly states the action: open a port in a workspace and return a link that reaches it. It also imparts a distinct outcome ('something a person can open') and an idempotence nuance that separates it from the sibling revoke_port/list_ports. No ambiguity about what the tool does.

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

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

The description gives a clear use context: converting a locally built app into something publicly openable via a link. It does not explicitly say 'use list_ports to inspect' or 'use revoke_port to remove', so alternatives are not explicitly contrasted, but the primary use case is clear enough for selection.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. It adds meaningful behavioral context: one credit equals one standard workspace for one minute, and paused workspaces consume no credits. This goes beyond the annotation and helps anticipate 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?

The description is extremely concise: two sentences, no waste. The first sentence states the action and subject, and the second adds the only necessary definitional detail. It is front-loaded and immediately understandable.

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 zero-parameter, read-only tool with strong annotations, the information provided is nearly complete. The agent knows what the tool does and what a credit means. It does not explicitly describe the output format or type, but for a simple balance query the semantics are sufficiently clear.

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?

No parameters are defined in the schema, so there are no parameter semantics to convey. The description appropriately does not fake parameter details; the baseline of 4 fits because there is nothing missing or misleading.

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: 'Show this account's remaining compute credits.' It also adds a precise definition of what a credit is, making the tool's purpose unambiguous and clearly distinct from all sibling workspace-management tools.

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

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

There is no explicit when-to-use/when-not-to-use guidance or named alternative, but the tool is the only credit-balance tool among its siblings, and its purpose is clear from the first sentence. The credit consumption semantics in the second sentence help the agent reason about when checking the balance matters.

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 indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context by explaining that every start is cold and that files survive while running processes do not, which clarifies what 'workspace state' means and warns against expecting process state.

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 concise, information-dense sentences. The description leads with the core return concept—head snapshot, log progress, and fork tree—then adds the useful persistence caveat. There is no filler or repetition of schema or annotation details.

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

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

For a simple read-only tool, the description does enough to give an agent a reasonable mental model of what it returns and what semantics matter. It could be more explicit about the return format or naming of fields, but those are not structural requirements given the minimal schema.

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 only parameter is 'workspace', but the description never explains how to express it, whether it is an ID, name, path, or something else. Since schema description coverage is 0%, the description should ideally compensate by explaining the workspace identifier, but it does not.

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

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

The title clearly says 'Inspect workspace', and the description specifies what is inspected: head snapshot, log progress, and fork tree. This distinguishes the tool from siblings like list_workspaces or run_command. It is slightly indirect in that the description does not explicitly say 'returns' or 'gets', but the meaning is clear.

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 this is the tool to consult when you need to understand a workspace's resumable state, especially what persists across a cold boot. However, it does not explicitly state when to prefer this over siblings like list_workspaces or create_workspace, nor does it give any 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?

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by specifying ordering ('oldest first'), including links, excluding revoked ports, and stating that a closed link never returns.

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 carry all essential information with no filler: what is listed, ordering, included content, and the important revocation behavior. The most relevant fact is front-loaded.

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 strong annotations and a single simple parameter, the description is complete. It conveys what the user sees, the order, the links, and the permanence of revocation. There is no unstated behavioral surprise 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?

The schema has 0% description coverage and only one required string parameter, `workspace`. The description adds meaning by tying the returned data to 'this workspace' and making it clear that the tool is scoped to a particular workspace. It does not provide format or value guidance, but the parameter is self-evident.

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'), a specific resource (ports), and a specific scope (the current workspace). It also clarifies the output format ('oldest first, with their links'), which distinguishes it clearly from related tools like `expose_port`, `revoke_port`, and `list_workspaces`.

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 provides clear context for when to use the tool: when you want the web-exposed ports of a given workspace and their links. The remark about revoked ports is also useful for setting expectations, but it does not explicitly name alternative tools or state when not to use this 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 cover the read-only/idempotent/non-destructive safety profile. The description adds useful context beyond annotations: results are scoped to the account and include a fork count per workspace. That is meaningful behavioral and output 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?

A single sentence captures the action, the scope, and the output detail. It is front-loaded and contains no filler or redundancy.

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 zero-parameter, read-only list tool with no output schema and a small sibling set, this description tells the agent exactly what the tool does, what scope it covers, and what result shape to expect. Nothing critical 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?

The tool has zero parameters, so the baseline is 4. Nothing needs to be added; the description correctly focuses on scope and output rather than inventing parameter details.

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

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

The description names a specific verb and object ('List this account's workspaces') and states a distinguishing detail ('how many forks each has'). This clearly separates it from get_workspace and the create/delete/checkpoint workspace sibling tools.

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 use case is clear: get an overview of all workspaces for the account. It does not explicitly name alternatives or exclusions, but the list semantics and scope make the appropriate context obvious enough for a 4.

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

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

The description adds critical behavioral detail beyond annotations: files survive, running processes do not, the workspace cold-boots, and the next run_command resumes it. It also discloses billing and archiving constraints. No contradiction with the annotations exists.

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 concise without sacrificing key behaviors. Every sentence adds value: persistence, cold-boot, resume behavior, billing consequence, and the archiving constraint. Crucially, the most important semantic facts come first.

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?

The tool's behavioral, financial, operational, and lifecycle context is well covered. It explains what happens when paused, what to do next, and why pausing is recommended. No output schema exists, so not explaining return values is acceptable.

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 schema has one required workspace parameter with 0% description coverage, and the description does not explicitly clarify its identifier format. However, the single self-describing parameter and the phrase 'workspace's disk' make the mapping reasonably inferable. It adds little 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?

The description states a specific action ('save the workspace's disk and stop the meter') and clearly frames the tool as pausing a workspace. It also distinguishes the behavior from non-pause operations by describing what survives and what does not.

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 explicitly says 'Pause when you are done' and gives clear context for when pausing is needed: a running workspace costs credits and cannot be archived. It does not explicitly name alternatives such as checkpoint_workspace, but the guidance is strong and actionable.

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

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

The description adds valuable non-obvious behavior: the link dies on the visitor's next request, re-opening later yields a DIFFERENT link, and the operation is not reversible. These go beyond annotations like destructiveHint and idempotentHint and tell the caller exactly what to expect.

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 tightly packed sentences deliver the essential effect, the timing, and the critical non-reversible caveat. Every word earns its place; there is no filler or repetition.

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-idempotent operation with only two required params, the description contains enough information to understand the action and its consequences. It could clarify what happens if the port is already closed, but the current wording still gives a clear mental model.

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 schema document shows 'port' and 'workspace' with no descriptions, so the tool description must compensate. It provides some semantic context for the 'port' concept, but none for 'workspace' or how it relates to the port. With 0% schema-description coverage, this is insufficient.

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 action ('close') and a clear resource ('one port to the web'). It distinguishes itself from the obvious sibling expose_port and list_ports by describing the actual effect of revoking a port.

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?

Provides explicit guidance: 'revoke only when the people holding the current one should lose it.' It doesn't name the alternative tool but clearly implies re-opening (via expose_port) would create a different link, which serves the same routing purpose.

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

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

The description adds useful behavior beyond the annotations: it is a one-shot command, a shell must be requested, and the workspace is forwarded to serve the command. The annotations already cover read-only versus destructive and idempotency, so the description does not need to restate them.

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 plus a short example carry all the essential instruction without redundancy. The most useful guidance ('Not a shell', shell example, paused-workspace behavior) appears immediately and 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?

The essential contract is complete: what is run, how to pass arguments, how to get a shell, and the behavior of a paused workspace. It stops short of detailing cwd and env defaults or the exact return shape, but no output schema is present and the parameter names provide enough guidance for the key usage.

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 only 20%, and the tool description compensates mainly for argv by making it explicit that argv is a list and that a full shell invocation such as /bin/sh -lc is required when shell syntax is wanted. Parameters like cwd, env, and workspace are self-evident by name, but are not enriched by the description.

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 starts with a specific verb and resource: 'Run one command in a workspace,' and names the outcome: 'get its exit code and output.' The explicit departure from a shell distinguishes it clearly from shell-like behaviors without relying on the parameter 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 first sentence makes the scope obvious, and the 'Not a shell' instruction tells the agent to ask for a shell explicitly when shell features are needed. It does not list sibling tools, but the route to a shell invocation is clear enough for correct use.

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