scratch-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.2.4
Disambiguation5/5
Every tool has a clearly distinct purpose, and even closely related pairs are explicitly differentiated by context (open_project vs open_scratch_project, run_project vs vm_green_flag, screenshot vs screenshot_jpeg). The resource and action each tool targets is unambiguous.
Naming Consistency4/5
The vast majority of tools follow a clear verb_noun snake_case pattern like add_sprite, remove_costume, and set_variable. Minor deviations such as project_info, reload, and vm_green_flag break the otherwise predictable pattern slightly.
Tool Count2/5
43 tools is far beyond the typical well-scoped server count, even though the domain is broad. The surface includes several closely related families—screenshots, desktop run/stop, and VM run/stop—that make the set feel heavier than necessary.
Completeness4/5
The server covers the core lifecycle well: opening/saving projects, sprite and asset CRUD, variables/lists, comments, block patching, publishing, and VM testing. Minor gaps exist such as no broadcast removal, no costume/sound renaming or replacement tools, and no account-level project listing.
Average 3.8/5 across 42 of 43 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under Mozilla Public License 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'update,' which implies mutation, but doesn't disclose side effects, whether unspecified properties are preserved, any permission requirements, or validation constraints (e.g., valid ranges for tempo, volume, or transparency). This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that gets directly to the point. It efficiently lists the properties, which is easy to scan. However, its brevity comes at the cost of necessary detail, but that is penalized in other dimensions. For conciseness itself, it is well-structured and avoids verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description must compensate fully. It fails to explain parameter meaning, any prerequisites (e.g., a project must be open), or the tool's effect on existing values. This makes the tool effectively unusable without external knowledge or trial and error.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no textual explanations for parameters. The description lists the parameter names (tempo, video state/transparency, volume) but doesn't define their meaning, valid ranges, or the meaning of enum values like 'on-flipped'. This leaves an agent without necessary context to populate values correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (stage-level properties), and lists the specific properties covered: tempo, video state/transparency, volume. This is a specific verb+resource pairing that distinguishes it from sprite-level or other tools, though it doesn't explicitly name alternatives like set_sprite. It effectively conveys the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus its siblings. The sibling list includes set_sprite, patch_target, and others that could overlap in functionality, but the description doesn't mention any decision rules, prerequisites, or exclusions. An agent would have to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry behavioral disclosure. It mentions 'update' implying mutation but does not clarify side effects, partial updates, error conditions (e.g., if the sprite doesn't exist), or whether changes are reversible. Critical information for a mutating tool is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is under-specified. It is not structured to guide usage, and the ellipsis suggests incomplete coverage. While short, the brevity comes at the expense of necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters, no schema descriptions, and no annotation, the description is insufficient. It doesn't explain what each property means, the expected value ranges, or the effect of omitting properties. Missing output schema and no guidance on invocation make it hard for an agent to call correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% parameter descriptions, so the description must compensate. It mentions a few parameters (position, size, direction, visibility) but skips volume, draggable, layerOrder, rotationStyle, and does not explain units, ranges, or constraints for any. The description adds minimal value over the schema's bare type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates sprite properties and lists representative examples (position, size, direction, visibility). It distinguishes the resource (sprite) from generic target-related tools, though it does not explicitly differentiate from patch_target which may overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like patch_target or set_stage. The description provides no context on selection criteria, e.g., whether this is the go-to setter for sprite properties or if patch_target is preferred for more complex changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only says 'create or replace', implying destructive mutation, but does not clarify whether existing items are wiped, whether the target is auto-created, or any side effects. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is extremely concise and front-loaded with the verb 'create or replace', making it easy to scan. However, its brevity is the reason it lacks depth, so while it is concise, that brevity is not an asset here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and all three parameters undocumented via description, an agent is left without critical information: what 'target' means, whether the list is fully replaced, how items are formatted, and any error conditions. This is entirely inadequate for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must clarify all parameters. It mentions 'by name' (covering the name parameter) and 'on a target' (vaguely covering target), but does not explain what 'target' refers to or what 'items' are. This adds only minimal meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create or replace) and the resource (a list) on a target by name. It effectively distinguishes this from sibling tools like delete_list (which removes) and set_variable (which handles variables), though it does not detail the exact behavior of replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., whether the target must exist), nor does it contrast with delete_list or mention scenarios where a different tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'delete,' which implies destructive action, but does not disclose side effects (e.g., whether deletion is permanent, whether it fails if the list is missing, or whether it affects dependent blocks). No additional context is offered beyond the obvious mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. It contains no fluff or redundant phrasing, making it efficiently scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and zero schema coverage, the description should provide richer context. It fails to explain what 'target' means in this domain, what happens on success or failure, or whether the operation is idempotent. For a destructive tool, this is insufficient for an agent to invoke it reliably without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for the parameters. It mentions 'from a target by name,' which hints that 'name' is the list's name and 'target' is the container, but it does not specify acceptable formats, constraints, or which of the two is the primary identifier. The parameters remain largely self-explanatory from their names, but the description adds minimal semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Delete a list') and its scope ('from a target by name'). It specifies the resource type (list), which differentiates it from sibling deletion tools like remove_sprite or remove_costume. However, it does not elaborate on what 'target' refers to, leaving slight ambiguity for an agent unfamiliar with the domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, or any conditions or prerequisites. The description only states what it does, not when it should be invoked. For instance, it does not mention whether the list must exist or whether this is the only deletion method for lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('remove') but does not mention that this is a destructive operation, what happens if the target or sound does not exist, whether changes are reversible, or any side effects on the project. Critical behavioral information is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. It is front-loaded with the core action and resource. While it is concise, it omits necessary details, but that is a completeness issue, not a conciseness issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, this description is incomplete. It fails to explain what 'target' refers to, how names are matched, error handling, or any prerequisites. Given the complexity of the surrounding toolset (many sibling tools), more elaboration is needed for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate for the lack of parameter metadata. It only clarifies that 'name' refers to the sound's name, but 'target' is left ambiguous—it could be a sprite, stage, or something else. This is insufficient for an agent to correctly populate the parameters without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove), the resource (a sound), and the scope (from a target by name). It is specific enough to distinguish from sibling tools like remove_costume or add_sound, and no tautology is present.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when this tool should be used versus alternatives. There is no mention of prerequisites, situations where this tool is preferable, or when to avoid it (e.g., if the sound is not present). The description is purely declarative with no context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. 'Stop running' implies mutation but lacks details on reversibility, side effects on the VM, or data persistence. It does not clarify what exactly is halted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence that is front-loaded and efficient, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool without output schema or annotations, the description is too sparse. It leaves unclear the meaning of 'userscripts' and how this action differs from vm_stop, failing to provide enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides complete coverage. The description adds nothing about parameters, and the baseline of 4 applies because there is nothing to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'Stop' is clear, but the resource is ambiguous: 'running in connected TurboWarp Desktop userscripts' might mean stopping the project or the userscripts themselves. It doesn't clearly differentiate from siblings like vm_stop or run_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as vm_stop or run_project. No prerequisites or selection criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention side effects (e.g., overwriting existing costumes), error handling, or reversibility. The description is purely functional and lacks behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the action and resource. There is no wasted text, and it is easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no annotations, and no output schema, the description is too sparse. It omits important context such as parameter roles, return behavior, and error conditions. An agent would need additional information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers only 3 of 6 parameters (50%), and the description adds nothing beyond the schema. It references the image file on disk, which aligns with 'path', but does not explain 'name', 'rotationCenterX', 'rotationCenterY', or 'dataFormat'. The description fails to compensate for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a costume'), the resource ('costume'), the target (sprite or stage), and the source (image file on disk). It is specific and distinguishes from sibling tools like remove_costume and add_sound.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention conditions, prerequisites, or exclusions. It only states the action without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the output's content but does not mention read-only behavior, error handling for invalid names, whether a project must be loaded, or how this differs from get_target_json in terms of output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single tight sentence that front-loads the core purpose and key output details. No redundant words or filler; every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description covers the basic return content but leaves important context unstated: how the output is structured, whether this is a friendly wrapper vs get_target_json, and what happens on error or missing targets. It is minimally adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter already has a clear description ('Sprite name, or "Stage"'). The tool description reinforces this by mentioning 'a sprite or the stage' but adds no new format, constraint, or usage detail beyond the schema, matching the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource (one target, either a sprite or the stage) and what is included ('full details', 'variables and lists'). It communicates the retrieval purpose well, though it does not explicitly differentiate from the sibling get_target_json, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to choose this tool over alternatives such as get_target_json or list_sprites. The only contextual hint is 'for one target', which implies single-target retrieval, but there are no explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It does not disclose that this is a destructive mutation, whether it requires an open project, or what happens if the costume does not exist. The description is minimal and leaves the agent guessing about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence with no unnecessary words. The core action and object are front-loaded, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, this description is too sparse. It lacks information about prerequisites (e.g., project loaded), error behavior, and the effect on the project state. An agent cannot reliably call it without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description offers only 'by name' to hint at the name parameter. It does not explain what 'target' refers to (e.g., sprite, stage) or any constraints on the values. This is insufficient compensation for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (remove), a resource (costume), and the scope (from a target by name). This distinguishes it from sibling tools like add_costume or remove_sound.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention conditions, prerequisites, or exclusions. The description simply restates the operation without contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose side effects. It only says 'rename' without noting if it is destructive, whether references are updated, or if replacing an existing name is allowed. This is a mutation with zero behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loads the action. Could be extended with necessary details without being overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description omits error behaviors, return value, and any special handling for the stage. Without annotations or output schema, an agent has no information about success/failure or edge cases. For a 2-parameter rename, this is borderline but lacks enough context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameters. It does not mention that 'name' identifies the target sprite/stage and 'newName' is the replacement. The names are somewhat self-explanatory, but the description adds no explicit mapping or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'rename' with explicit resource 'sprite (or the stage)', distinguishing it from sibling tools like patch_target or set_sprite. The parenthetical clarifies stage support, adding precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives like patch_target, or any prerequisites. No mention of whether it applies to selected target or requires explicit name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'Press the green flag', implying a start action, but does not disclose side effects, error handling, or whether it blocks or is asynchronous. The mention of 'connected' hints at a prerequisite but is not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is perfectly concise and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool, the description is mostly sufficient but lacks context about the required state (e.g., a project must be loaded) and does not differentiate itself from the similar vm_green_flag sibling. This could leave an agent unsure which to invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the schema is trivially complete. The baseline for 0 params is 4; the description adds no confusing info, so this score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Press the green flag in connected TurboWarp Desktop userscripts' clearly indicates it runs/executes the current project using a familiar Scratch idiom. It distinguishes from siblings like open_project and save_project, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as vm_green_flag or stop_project. It doesn't state prerequisites (e.g., a project must be loaded) or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides minimal behavioral detail. It does not mention side effects such as overwriting existing sounds, name conflicts, or required project state. With no annotations, the description carries the full burden and it falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource. It is concise and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and only 50% parameter coverage, the description is too brief. It does not address necessary parameters like 'name' and 'dataFormat', nor does it state any prerequisites or behavioral notes needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds little to the schema. It clarifies that the sound comes from a disk file, but does not explain the 'name' or 'dataFormat' parameters, which lack schema descriptions. Since schema coverage is only 50%, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add), the resource (sound), and the destination (sprite or stage), and specifies the source (audio file on disk). This distinguishes it from siblings like add_costume and remove_sound.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like add_costume or remove_sound. The context implies it is for adding audio files, but there are no exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavior/safety burden. It usefully discloses that the sprite is created empty and that opening it in the editor requires a costume first. However, it is silent on side effects, defaults for optional properties, whether a project must already be open, and error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, each carrying meaningful information: what the tool does and a critical prerequisite. The core action is front-loaded and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 10 parameters, no annotations, and no output schema, the description is too sparse. It covers creation and the costume prerequisite but omits project context, defaults, return behavior, and parameter semantics, leaving the agent uncertain about how to invoke it safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation for any of the 10 parameters (x, y, size, volume, visible, direction, draggable, layerOrder, rotationStyle). The only parameter-related hint is the costume prerequisite, but 'costume' is not even a parameter. The description fails to compensate for the schema's lack of parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and object: 'Add a new, empty sprite.' This distinguishes it from sprite-modification siblings like set_sprite and patch_target, and from removal via remove_sprite. The word 'new' also signals creation rather than editing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It directly states when to use the tool (to create a sprite) and gives a clear workflow prerequisite: add at least one costume before opening it in the editor. It does not explicitly mention alternatives or when not to use it, but the creation context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits itself. It only says 'delete', which implies mutation, but does not mention side effects (e.g., irreversible, fails if variable does not exist), required permissions, or error behavior. For a destructive operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no filler. The action and scope are front-loaded, making it efficient for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters and no output schema, but it lacks any mention of error conditions, idempotency, or differentiation from related tools. While not severely incomplete, it leaves room for ambiguity in edge cases and alternative tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameters. It explains 'name' as the variable name and 'target' as the object from which the variable is deleted. This provides meaningful context beyond the bare type strings, though it does not specify formats or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), the resource (a variable), and the scope (from a target by name). It distinguishes itself from siblings like delete_list (different resource type) and set_variable (different operation) without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as set_variable or delete_list. The description only states the basic function without any context about prerequisites, typical scenarios, or exclusions. An agent has no explicit help in deciding between deletion and modification or between variable and list deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state the return contents (position, size, media) and implies a read-only listing, which is reasonable. However, it doesn't mention ordering, performance, or any side-effects, though for a simple list these may be assumed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. It conveys purpose and return contents efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters and no output schema, the description adequately states what is returned (position, size, media). For a simple no-argument list tool this is essentially complete, though it doesn't describe the exact return data structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no schema coverage gap to compensate and no parameter semantics to document. The baseline 4 applies since nothing needs explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb 'List' and resource 'sprites' with the returned fields (position, size, media). The phrase 'every sprite' implies a full list, distinguishing it from single-target get_target, though it doesn't explicitly name the sibling difference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus get_target or list_blocks, no exclusions, and no context about the project being open or load state. Usage is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses that assets used exclusively by the sprite are also deleted, which is a useful cascading side effect. However, it doesn't state reversibility, permissions, or what happens to scripts or other references.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the primary action and includes a valuable qualifier. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter delete operation, the description covers the core behavior and a key side effect. It lacks details about error conditions, project state requirements, and whether the action is undoable, but these are minor for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one string parameter, 'name', with no description (0% coverage). The description does not explicitly connect the parameter, but the tool name and purpose make clear that 'name' identifies the sprite. No additional semantics are added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (delete) and resource (sprite), and adds a clarifying scope detail (assets only it used). Distinguishes from sibling remove_costume/remove_sound by targeting the sprite itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to choose this tool over alternatives like remove_costume or set_sprite. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses two behaviors: the default path behavior and the TurboWarp Desktop reload side effect. However, it does not mention whether the operation overwrites existing files, what happens if the project isn't open, or any error/return behavior. This is partial disclosure but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff, front-loading the core action and then adding the default-path detail and a side effect. It is efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a save operation with no output schema or annotations, the description covers the essentials but omits key details like return value, overwrite semantics, and behavior of the compressionLevel parameter. It is adequate for a straightforward call but not fully complete for an agent needing to handle edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies the 'path' parameter by repeating the default behavior, but the schema already covers that. The 'compressionLevel' parameter is undocumented in both schema and description, and the description adds no meaning for it. Given only 50% schema coverage, the description fails to compensate for the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Write the open project back to an .sb3 file') with a specific verb and resource, and distinguishes it from siblings like open_project (load) and reload (reload). The default path detail adds precision. There is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you want to persist the current project to disk) but does not explicitly state when not to use it or suggest alternatives. There is no mention of complementary tools like push_to_scratch or how saving differs from exporting. The guidance is implied rather than explicit, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It clearly discloses that the operation mutates state by creating or updating a variable, but it does not mention edge cases, overwrite semantics beyond 'update', target existence requirements, or any return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It communicates the operation, scope, and key parameter roles without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter mutation tool, the description plus schema covers the essential invocation details: what to target, what variable name, and what value. It is slightly incomplete in that it offers no explicit guidance on when not to use it or how it interacts with sibling variable tools, but those gaps are minor for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% because only target has a description. The phrase 'by name' clarifies the role of the name parameter and 'on a target' clarifies target scoping, but the value parameter is left only to its obvious meaning and the schema's type union.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Create or update') and a specific resource ('a variable on a target by name'). It distinguishes the tool from delete_variable and other sibling mutation tools because it explicitly covers both creation and update behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as delete_variable, nor any exclusions or prerequisites. The intended use can be inferred from the name and siblings, but the description itself is silent on routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It says the tool loads a file from disk but does not mention potential side effects, such as overwriting the current project or losing unsaved changes, nor does it note prerequisites like ensuring a connected TurboWarp Desktop. The 'without going through save_project' phrase hints at a workflow nuance but leaves important behavioral details implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant wording. The primary action is front-loaded, and the usage guidance follows naturally. Every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool, the description covers the core action and default behavior. However, it omits important context such as the requirement for connected TurboWarp Desktop userscripts and the potential impact on unsaved project state. Given the lack of annotations and output schema, this makes the definition only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the path parameter and its default behavior. The tool description merely restates this ('defaults to the open project') and adds no additional semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: telling connected TurboWarp Desktop userscripts to load an .sb3 from disk, with a default to the open project. It uses a specific verb and resource, and the contrast with save_project helps distinguish it from related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use after editing on disk without going through `save_project`,' giving a clear scenario for when to invoke this tool. However, it does not mention alternative tools like open_project or vm_load, nor does it specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It clearly discloses that this injects input events and gives stage coordinate ranges. However, it does not describe important behavioral traits like whether inputs are queued, whether they take effect only while the VM is running, or what happens to a pending ask-and-wait prompt.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences with no filler. The core purpose and input types are front-loaded, and the coordinate-bound detail is placed second where it is relevant to parameter use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for basic invocation but leaves out operational context: whether the VM must already be running, whether inputs are processed sequentially or batched, how answer interacts with a pending ask-and-wait block, and what the tool returns. These gaps matter more because there is no output schema and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 80%, so the schema already documents the parameters well. The description adds helpful grouping (keys, mouse, answer) and coordinate ranges, but those ranges already appear in the schema. It does not meaningfully elaborate beyond the schema for parameter interpretation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: feed input into the headless VM. It enumerates the concrete input types (key presses, mouse position/clicks, answers to ask and wait), which clearly distinguishes it from sibling VM tools like vm_run, vm_stop, and vm_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by saying 'the way the editor would,' and it lists the supported input categories. However, it never explicitly states when to use this tool versus alternatives, nor does it mention prerequisites such as the VM needing to be running or a project needing to be loaded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It does add context by clarifying the file is loaded 'into memory for editing,' implying no direct disk write. But it does not mention failure behavior, whether an already-open project is replaced, or other editor-state side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler words. Every element contributes: the action, the resource type, the source, and the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with low complexity, the description provides the essential invocation details: the local file path, the expected file format, and the operation's in-memory editing purpose. Return behavior and interaction with an existing open project are not specified, but these are minor gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single `path` parameter, so the structural schema already documents the parameter. The description adds only the '.sb3' file-type context, which is already reflected in the schema's parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Load') with a clear resource ('.sb3 file from disk') and purpose ('into memory for editing'). This distinguishes it from sibling tools like open_scratch_project, reload, and vm_load by emphasizing local disk vs. other load contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied rather than stated outright: loading a local .sb3 file for editing. However, there is no explicit guidance about when to prefer this tool over alternatives such as open_scratch_project, reload, or vm_load.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the key idempotent no-op behavior, which is the main operational nuance an agent needs. Return values and error cases are not covered, but the tool is simple enough that this is a reasonable level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with the action and target front-loaded. The no-op clause adds important behavioral information without any unnecessary padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-string-parameter tool with no output schema and no annotations, the description covers the core action, scope, and duplicate behavior. Parameter meaning and return/error behavior are implicit, but the tool is simple enough that no major contextual gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required string `name` with 0% description coverage. The tool description implies that `name` identifies the broadcast message being added, but it does not explicitly state constraints, formatting, or uniqueness rules. It adds enough meaning to connect the parameter to the action, but does not fully compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Add') and a concrete resource ('broadcast message to the project'), and the no-op clause distinguishes it from other add_* siblings by describing duplicate behavior. It is immediately clear what this tool does and how it differs from related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use statement, nor a named alternative. The wording 'to the project' and 'no-op if it already exists' implies this is the broadcast-specific add operation and is safe to call repeatedly, but the choice among add_* sibling tools is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Summarize' implies a read-only operation with no side effects, but the description does not explicitly state that it is non-destructive, nor does it explain what exactly the summary contains (e.g., structure, format, or level of detail). It provides minimal behavioral context, which is adequate for a simple read tool but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action ('Summarize the open project') and then lists the specific aspects covered. There is zero waste, and it is appropriately concise for the tool's simple purpose. Every word contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple informational tool with no parameters and no output schema, the description is fairly complete: it tells the agent what the tool does and what aspects it covers. However, it does not specify whether the summary is textual, structured, or how detailed it is. Given that an agent might need to know the return format to parse the result, this is a minor gap but not critical for a summarizer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (trivially, since there are no parameters to document). The description does not need to add parameter semantics, and the baseline for high schema coverage is 3; for zero parameters this is trivially satisfied. The description adds no parameter info but none is required, so a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Summarize') and resource ('the open project'), and explicitly lists the aspects covered (targets, extensions, monitors, meta). This distinguishes it from sibling tools like list_sprites or get_target, which focus on individual components. The purpose is unambiguous and precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for obtaining an overview of the project, but it does not explicitly state when to use it versus the many sibling tools (e.g., list_sprites, get_target, get_target_json). It lacks guidance on when not to use it or mention of alternatives, leaving the agent to infer that it is for a high-level summary rather than detailed per-component access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does this well by revealing a non-obvious side effect: if the comment was attached to a block, the block's comment back-reference is cleared. This is valuable beyond the obvious delete action, though it does not address error behavior or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The primary action is front-loaded, and the important side effect is clearly separated as a conditional consequence. Every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 and no annotations, the description is largely complete. It gives the core behavior and the key side effect. Minor gaps include error handling and whether deletion is reversible, but these are not essential for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both parameters. The description adds little beyond restating that deletion happens by id and that the comment exists on a target. This meets the baseline but does not enhance parameter understanding further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('workspace comment'), and the targeting mechanism ('by id'). It is immediately distinguishable from siblings like add_comment, set_comment, and list_comments by the explicit delete verb and object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a workspace comment needs to be removed. However, it does not explicitly contrast it with set_comment or list_comments, nor does it state when not to use it. Usage is inferable but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the partial-update behavior and the blockId detaching mechanism (empty string/null), which is useful. However, it does not mention what happens if the comment id does not exist, whether there are permission requirements, or any error behavior. These gaps leave the agent partially uninformed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the action ('Update an existing comment'), states the target and id, and lists the changeable fields along with the detach behavior. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description covers the essential information an agent needs to call it correctly: what fields can change, the partial-update behavior, and blockId detaching. It lacks return-format details, but with no output schema defined, this is not critical. Slightly more detail on error conditions would raise it further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all 9 parameters with descriptions (100% coverage). The description adds value beyond the schema by explaining the partial-update semantics and the special detach convention for blockId, which is not fully inferable from the parameter descriptions alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing comment on a target by id, enumerating the mutable fields (text, position, size, minimized, blockId). This specific verb and resource distinguish it from sibling tools like add_comment and remove_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing comments ('existing comment') and the partial-update semantics ('Only the fields you pass change'), but it does not explicitly contrast with adding or removing comments. There is no explicit 'use this when' guidance, leaving alternatives to inference from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description must carry the burden of behavioral disclosure. It does disclose the core side effect—every running script is stopped—but it does not say whether the VM execution state is reset, whether the action is reversible, or what happens to the project afterward.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the action, scope, and location with no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter stop command, the description covers the essentials: what is stopped and where. It is slightly incomplete only because it does not clarify the relationship to sibling tools like stop_project or describe the resulting VM state, but this is a minor gap for such a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already fully covers the input surface; the description does not need to explain any parameters. Baseline for no-parameter tools is 4, and nothing is missing here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Stop'), the scope ('every running script'), and the resource ('the headless VM'), which makes the tool's purpose unmistakable. This is more specific than the title and distinguishes it from project-level controls like stop_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: choose this tool when all scripts in the headless VM need to be halted. However, the description gives no explicit guidance about when not to use it or which sibling (e.g., stop_project) would be more appropriate for a different stopping scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose effects. It mentions it's headless, reflects in-memory edits, and returns a snapshot. However, it does not disclose potential side effects such as whether it resets the VM state or overwrites previous load, nor does it describe the snapshot format. These are gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, followed by usage nuance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (0 params, no output schema), but the description omits details like the snapshot structure and error behavior (e.g., if no project is open). For an agent to use it correctly, knowing what the snapshot contains would be helpful. So it's adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description adds no parameter information. Baseline for 0-param tools is 4, and there is nothing else needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Load', the resource 'open project', and the target 'headless Scratch VM (TurboWarp, JIT)'. It distinguishes from siblings by emphasizing headless operation, which differentiates it from run_project or vm_run. This is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context: it's for running and testing without a browser, and it explicitly says to call again after editing to reflect changes. However, it does not explicitly contrast with sibling tools like run_project or vm_run, so the agent has to infer that loading is a prerequisite for running. It lacks explicit exclusions like 'use run_project for execution'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It discloses the return structure (id, text, blockId or null) and explains the meaning of null (floating free vs attached to a block), which is valuable behavioral context. It also clarifies the tool has no side effects (a list operation). This goes beyond what the schema offers, though it doesn't mention pagination or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero fluff. The first sentence states purpose and identifies the resource; the second sentence precisely details the return shape. Information is front-loaded, and every clause contributes to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema), and the description covers the essential return format. It fully explains what an agent will receive. Minor gaps like ordering or error conditions are not critical for a list operation, and the description is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'target' parameter, which is fully described in the schema as 'Sprite name, or "Stage".' The description does not add any additional meaning to the parameter, so it relies on the schema. Baseline 3 applies because the description does not need to compensate for coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'a target's workspace comments', and differentiates from sibling comment tools like add_comment and remove_comment by focusing on the listing operation. It also provides concrete identification ('yellow sticky notes shown in the editor') which removes ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is unambiguous: the tool lists comments for a target. No explicit mention of alternatives or when-not-to-use, but the context is clear enough that an agent would know to use this for retrieval rather than modification. The description does not name sibling tools, but the verb 'list' implies its role in the comment workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the in-memory nature, the login requirement for unshared projects, and the save-back path. It does not mention failure modes or whether opening replaces an already-open project, but the key behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action, then essential prerequisites and follow-up. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool, the description covers the source, authentication requirements, in-memory behavior, and how to persist changes. It does not describe return values or error handling, but no output schema exists and the omission is minor for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the schema already stating the projectId is 'The scratch.mit.edu project id.' The description only repeats 'by id' without adding format details such as whether a URL or numeric id is expected, so it provides little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Download a project from scratch.mit.edu by id') and clearly identifies the resource, distinguishing it from local project operations. It also clarifies the in-memory editing context, which differentiates it from save/project-info siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when login is needed and directs the user to push_to_scratch for saving edits. It does not explicitly discuss alternatives like open_project, but the usage context is strong enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the session is kept in memory only for this server process, that credentials default to environment variables, and that saving/publishing require confirmation. It doesn't mention potential rate limits or security nuances, but for a login tool this is a solid level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The core purpose and effect are front-loaded, followed by the env-var fallback and session lifetime. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a login tool with two optional parameters fully covered by the schema, the description is complete. It explains the consequences (session in memory) and the confirmation behavior. One minor gap: it doesn't explicitly state that login must occur before other tool calls, but that is strongly implied by the purpose statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes both parameters, including their env-var defaults. The description restates the defaults but adds no new syntax or meaning beyond the schema. Per the rubric, with 100% schema coverage this is a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (authenticate) and the target resource (scratch.mit.edu account), and explains why it matters (open projects, save edits, publish). It distinguishes itself from the many project/sprites tools by focusing solely on authentication, so an agent can easily tell this is the login step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies that login is a prerequisite for other server operations (opening projects, saving, publishing) and explains the confirmation flow for writes. It doesn't explicitly say 'use before other tools' or list alternatives, but given the sibling list has no other auth tool, this is clear enough. The env-var default is a handy usage note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the output format in detail: shape, inputs with sb3 shadow encoding, fields with dropdown options, and an example block JSON. It also discloses that placeholders like `<…>` must be replaced, menu inputs need a matching shadow block, and dynamic menu options are populated from the open project. This goes well beyond a simple 'get schema' statement, though it does not cover error handling or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but densely packed with necessary details. It front-loads the main purpose and then provides crucial usage specifics (shadow encoding, placeholders, dynamic menus). While it could be trimmed slightly, every sentence carries operational meaning and earns its place, making it efficient for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description must convey what the tool returns, which it does thoroughly: schema structure, inputs, fields, example JSON, and interpretation notes. It also explains the context of use relative to patch_target and the role of the target parameter. It lacks explicit error behavior for unknown opcodes, but for an agent needing to fetch and use a block schema, the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% coverage with descriptions for both parameters. The tool description adds further semantic depth: it clarifies that 'opcode' is a block opcode with examples, and explains that 'target' is used specifically to populate dynamic menus with that sprite's costumes and sounds. This enriches the schema's bare definitions, so the description adds genuine value beyond the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: returns the full schema for one block opcode, including shape, inputs with shadow encoding, fields with options, and example JSON. It distinguishes itself from siblings like patch_target (writing blocks) and list_blocks by focusing on schema retrieval. The verb 'get' plus specific resource 'block schema' makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Read this before writing a block with patch_target', which is clear when-to-use guidance. It also explains when to pass the 'target' parameter (to populate dynamic menus) and mentions the need for shadow blocks for menu inputs. It does not, however, explicitly state when not to use this tool or name alternatives, but the context is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It details the contents of the snapshot (position, size, direction, etc.) but does not explicitly state that it is read-only or non-destructive, nor does it mention performance implications or side effects. The 'snapshot' framing implies read-only, but it falls short of disclosing all behavioral characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that starts with a clear headline ('A structured snapshot of the headless VM right now') and then lists all components. There is no filler, and every listed item adds value. It is appropriately sized for the complexity of a rich state snapshot.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description must fully specify what the tool returns, and it does so comprehensively: targets, variables/lists, monitors, bubbles, pending question, thread count, and errors. It also states the intended use (assertions). For a zero-parameter tool, this is complete enough for an agent to call and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% (empty schema). According to calibration rules, a baseline score of 4 applies because there is nothing to explain about parameters. The description does not need to add parameter semantics; it correctly focuses on the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('snapshot') and resource ('headless VM'), enumerating exactly what it captures (targets, variables, monitors, bubbles, etc.) and its intended use ('Assert against these rather than a screenshot'). It distinguishes itself from screenshot tools and other state-related siblings by focusing on structured data rather than pixels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use this tool ('Assert against these rather than a screenshot'), implying it is for verification/diagnosis instead of visual inspection. However, it does not explicitly mention alternatives like get_target for narrower state queries or when not to use a full snapshot. Thus the guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It reveals a key side effect: attaching to a block sets the block's 'comment' back-reference, which impacts the editor anchoring. It also clarifies that omitting blockId results in a free-floating comment. While it doesn't mention permissions or error behavior, it discloses the most important non-obvious side effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the main action front-loaded and the blockId distinction succinctly explained. No fluff or redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with 100% schema coverage and no output schema, the description adequately covers the pivotal decision (blockId vs free-floating) and points to get_target_json for block ID discovery. Other parameters like x, y, width, height, and minimized are fully specified in the schema. The description is complete enough for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline 3. The description adds value beyond the schema by explaining that blockId is a key in the target's blocks map and referencing get_target_json for lookup. It also frames blockId omission as intentional for free-floating comments, enriching the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Add), the resource (workspace comment), and the target. It explicitly distinguishes free-floating vs block-attached comments, and the reference to get_target_json further clarifies where blockId comes from. This fully differentiates it from sibling comment tools like set_comment and remove_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two usage modes (with or without blockId) and implies that this is for creating a new comment, while set_comment would modify and remove_comment would delete. It could explicitly name the alternatives, but the verb 'add' and the behavior description make the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and explicitly discloses the mutation: 'Adds the id to the project's `extensions` and, with a url, records it in `extensionURLs`'. It also reveals the editor fetch behavior for custom extensions via the loader URL. It stops short of a 5 because it says nothing about error conditions (unknown id, unreachable url) or idempotency of re-registering the same extension.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with the purpose and prerequisite front-loaded in the first. Every sentence earns its place: even the inline built-in ID list, though dense, is necessary reference data the agent needs to invoke the tool correctly. There is no filler and no repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter mutation with no output schema and no annotations, the description covers what the tool does, when it is required, how to call it in both branches, and exactly what project state it mutates. What's missing is edge-case behavior (error handling for bad IDs or failed fetches, repeated registration) and any mention of the return value, which are secondary for a simple command-like mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, placing the baseline at 3, but the description adds genuine value by enumerating all 11 built-in extension IDs — far beyond the schema's single 'e.g. "pen"' example. It also makes the conditional dependency explicit (url needed only for custom/third-party extensions) and justifies url's purpose ('so the editor can fetch it'), which the schema's one-liner doesn't convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 — 'Register an extension on the project' — and states the concrete behavioral consequence ('its blocks load and show in the palette'). It also names the prerequisite contract ('required before using any `<id>_…` extension block'), and since no sibling tool covers extension registration, an agent can select it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit trigger condition: enabling is required before any `<id>_…` block can be used, which tells the agent when to call it. It then branches the invocation logic — built-in extensions need only `id`, custom extensions also need `url` — providing clear conditional guidance. It doesn't name alternative tools or when-not conditions, but no sibling handles extensions, so the exclusion is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It discloses the re-encoding via sharp, the lossy nature, and the quality trade-off. It implies a return similar to 'screenshot' but does not explicitly state the return format, which is a minor gap given the reference to the sibling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the key behavior (JPEG, smaller payload) and then provide the trade-off and parameter note. No redundant phrases; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and full schema coverage, the description is nearly complete. It relies on the sibling tool for return semantics but that is sufficient. The only omission is an explicit statement of the return type, which is inferred from the sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and already describes the 'quality' parameter in detail (range, default, effect on size). The description only restates the parameter with no additional 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures the same stage image as 'screenshot' but re-encodes it as JPEG for a smaller payload. It names the sibling tool and distinguishes by output format and size, leaving no ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Prefer this version unless you need pixel fidelity,' and explains the trade-off that JPEG is lossy and may soften fine UI detail and flat color edges. This clearly tells the agent when to use this tool versus the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure and does it well: it states the returned content, notes the data is 'exactly as stored', and explains the default whole-object behavior versus subtree fetching with pointer. It does not mention error cases or auth, but for a read-only retrieval tool the key behaviors are adequately disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The description front-loads the core purpose, then immediately gives actionable workflow context (read first for patch_target) and parameter usage. Every sentence adds value and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema, the description fully covers what is returned, why to use it, and how to narrow the response. The patch_target workflow context and pointer examples give an agent everything needed to invoke the tool correctly in its primary use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaningful context beyond the schema by tying pointer paths to JSON Pointers into the object and giving concrete examples like '/blocks' and '/blocks/abc123'. It also clarifies that omitting pointer returns the whole target, reinforcing the schema's optionality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as fetching a target's complete raw project.json entry, listing its contents (blocks, costumes, sounds, variables, lists, properties) and the exact storage format. It distinguishes itself from siblings like get_target by specifying 'raw' and by framing this as the source for patch_target JSON Pointer paths.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Read this first to author a patch_target edit', giving a clear when-to-use scenario. It also explains how to use the pointer parameter to keep responses small. It does not explicitly contrast against siblings like get_target or list_blocks, but the workflow guidance is strong enough for an agent to know when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that publishing is public/outward-facing, requires login and ownership, and that it always prompts for user confirmation. This is substantial behavioral context beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, action first, then prerequisites and confirmation rule. No filler; every clause adds relevant information, and the key constraint is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple publish tool with 2 optional parameters and no output schema, the description covers prerequisites, behavior, and param usage fully. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, meeting the baseline. The description adds minimal extra value: it restates the confirm behavior but does not offer new parameter semantics beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Publish a project on scratch.mit.edu so it becomes publicly visible', with a specific resource and HTTP endpoint. It distinguishes itself from siblings like save_project or push_to_scratch by being solely about sharing/publishing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites (login and ownership) and a clear confirmation rule ('always asks the user to confirm first' and 'set confirm: true only after the user has agreed'). It does not name alternative tools or exclude scenarios, but the context is clear enough for an agent to know when to apply it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fully discloses execution mode (real-time, paced), stopping conditions (all scripts finish or budget), and the comprehensive return payload (sprite positions, variables, lists, monitors, bubbles, pending questions, thread count, errors, and an ordered events timeline). It also hints at internal behavior like waits, timers, and glides functioning correctly. No contradictions with annotations (none exist).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but every sentence earns its place. It opens with the primary action and return, then explains default execution, then enumerates the return contents, then highlights the unique events timeline. The front-loaded structure delivers the core purpose immediately, and the rest is organized logically. Minor redundancy in listing return fields twice (state snapshot and then details) but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description provides a thorough explanation of what is returned and when execution stops. It mentions the events timeline and its purpose (to assert sequence), which is valuable for an agent. It does not specify the exact JSON shape of the output, but given the descriptive list of contents, an agent can infer the general structure. The absence of explicit error-handling details or partial-state semantics is a minor gap, but overall the description is complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all four parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds semantics beyond the schema by explaining how the default behavior relates to parameters (e.g., 'runs in real time' ties to paced/seconds, 'budget elapses' ties to seconds/frames, 'until every script finishes' ties to untilIdle). This contextualization helps an agent reason about parameter combinations without opening the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Advance the headless VM' and 'return a state snapshot'. It clearly differentiates from siblings like vm_state (which likely returns state without advancing) by emphasizing progression and returning a timeline of events. The wording is not a tautology and precisely captures the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description details default behavior (real-time execution until scripts finish or budget elapses) and what the tool returns, making its purpose self-evident. It does not explicitly name alternative tools or state 'when not to use', but the clear semantics of advancing vs. inspecting (siblings vm_state, vm_green_flag) make the usage context obvious. A slight deduction for lacking explicit disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains what the catalog contains, how filtering works, and what happens when category is omitted. It does not describe the exact output shape or any error behavior, but for a read-only listing tool the described behavior is substantially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler. The first sentence states what the tool returns, the second gives the usage flow, and the third explains the parameter behavior. Every clause adds actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-optional-parameter catalog tool with no annotations and no output schema, the description is remarkably complete. It covers purpose, contents, valid parameter values, default behavior, and the relationship to get_block_schema. Nothing an agent needs to decide whether and how to call this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only says category is 'A core category or a built-in extension id.' The description adds the crucial default behavior, lists every valid core category and extension ID, and clarifies that passing category filters the catalog. Since there are no enums in the schema, this enrichment is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies what the tool returns: a catalog of standard Scratch block opcodes usable in a target's blocks map, including category, shape, and input/field names. It also distinguishes itself from get_block_schema by framing itself as the discovery step and get_block_schema as the fill-in step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: use it to discover opcodes, then use get_block_schema to learn how to fill one in. It also states the default behavior with no category and enumerates valid core categories and extension IDs for filtering. It stops short of explicitly saying when not to use this tool, though the alternative is clearly named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral disclosure burden. It discloses that this is the real renderer, requires a connected editor, depends on a userscript bridge, and that pixels are not a good substitute for values. It does not describe failure behavior or rate limits, but the key operational traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: what the tool does, how/where it works, the precondition, and explicit alternatives. The most important identifying information is front-loaded, with no redundancy or vague filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter screenshot tool with no output schema, the description is complete: it tells the agent the output type (PNG), the runtime context (live TurboWarp Desktop editor), the required setup (load/run first), and compares itself to relevant siblings. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to add to the input schema. The description appropriately focuses on preconditions and output format instead of parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Capture a PNG of the live stage from a connected TurboWarp Desktop editor.' It also names the mechanism (live-reload bridge + userscript) and distinguishes itself from the sibling screenshot_jpeg by specifying PNG format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides preconditions ('load and run the project there first via save_project/run_project') and gives clear alternative routing: prefer vm_state for logic checks, and use screenshot_jpeg for a much smaller payload. This is exemplary when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it discloses the key behaviors: it overwrites the online project, uploads costumes/sounds before writing project.json, requires authentication and ownership, edits the live project (so it is destructive), and always asks for user confirmation before proceeding. This is a thorough and honest account of side effects and prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the core action and outcome front-loaded, followed by prerequisites and the critical confirmation behavior. No wasted words; every sentence carries necessary information for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters, no output schema, and no annotations, the description covers all essential aspects: the operation, side effects, prerequisites, and the confirmation flow. An agent can correctly call this tool without further clarification, and the description is complete for the given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters, but the description adds vital context: it explains that 'confirm' should only be set true after the user agrees, and that 'projectId' defaults to the opened project. It also clarifies the confirmation mechanism ('used if the client cannot prompt'). This goes beyond the schema by explaining behavior and defaults, significantly aiding correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Save'), a resource ('the open project'), and a destination ('back to scratch.mit.edu'), while also clarifying the effect ('overwriting the online project's contents'). It distinguishes from siblings like save_project by specifying the remote target, so an agent can immediately understand what it does and how it differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: to push edits to the live online project, and it lists necessary preconditions ('Requires login and ownership'). However, it does not explicitly name alternatives or state when not to use it, such as pointing to save_project for local saves. This is clear context but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and it succeeds: it discloses side effects (clearing bubbles, pending question, errors) and confirms it does not advance time. This gives the agent the necessary behavioral expectations for a state-changing action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, with the main action and side effects in the first sentence, and the critical usage contrast and prerequisite in the second. No filler; every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter action with no output schema, the description fully covers what the tool does, its effects, what it does not do, and prerequisites. An agent can invoke it correctly with no further information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema correctly reflects that with no properties. The description doesn't need to explain parameters; the baseline of 4 for no-parameter tools is appropriate, and no additional semantics could be added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Press the green flag') and resource ('headless runtime'), and explains the exact effects (clears bubbles, pending question, errors, starts scripts). This clearly distinguishes it from sibling tools like vm_run and vm_load, which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says what the tool does NOT do ('Does not advance time on its own') and directs the agent to vm_run for stepping, and vm_load as a prerequisite. This leaves no ambiguity about when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses atomicity (patch applied atomically, unchanged on failure), advisory warnings for unknown opcodes/inputs, that patching costumes/sounds doesn't touch asset bytes, and that the agent is responsible for block consistency (ids, next/parent links). These are non-obvious behavioral traits critical for correct use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It front-loads the purpose in the first clause, then layers procedural steps and warnings without redundancy. The structure (main sentence, then 'Notes:') makes it easy to scan and retain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (RFC 6902 patching, modifying sprite scripts), the description is remarkably complete. It covers prerequisites (read get_target_json), how to build valid patches (list_blocks, get_block_schema), atomicity, warnings in the result, and scope limits (costumes/sounds). It also implicitly addresses the return via 'advisory warnings'. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema covers both parameters (name, patch) at 100%, the description adds significant value by explaining that paths are JSON Pointers into get_target_json output, how to discover block opcodes and shapes, and what the patch document represents. This goes well beyond the schema's basic type/description, guiding correct construction of the patch parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Apply an RFC 6902 JSON Patch to a target's raw JSON'), the resource (target's raw JSON), and the specific purpose (editing sprite scripts or fields not covered by higher-level tools). It explicitly distinguishes itself from siblings by mentioning 'any field a higher-level tool does not cover'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: it's for fields not covered by higher-level tools, and it directs the agent to read `get_target_json` first and use `list_blocks`/`get_block_schema` for block scripts. It also names alternatives for costumes/sounds (`add_costume`/`remove_costume`), making the decision tree clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![ScratchMCP MCP server](https://glama.ai/mcp/servers/AstroBlocksMod/ScratchMCP/badges/card.svg)](https://glama.ai/mcp/servers/AstroBlocksMod/ScratchMCP)

Score Badge

Copy to your README.md:

[![ScratchMCP MCP server](https://glama.ai/mcp/servers/AstroBlocksMod/ScratchMCP/badges/score.svg)](https://glama.ai/mcp/servers/AstroBlocksMod/ScratchMCP)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AstroBlocksMod/ScratchMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server