R3

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: the two-call report-then-confirm ritual, the fact that without confirm nothing is deleted, 'There is no trash and no undo', cascade effects (a model takes only-unused images with it, an HDR/EXR takes its preview), per-call permission requirements, and cross-project protection. This is exactly the additional context the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and resource list, and every sentence carries non-redundant information. It is dense, however, with layered parentheticals and em-dash asides that make some clauses hard to parse on first read, slightly diluting scannability.

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

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

An output schema exists, so return values need no explanation. For a destructive, permission-gated, cascading tool the description covers the confirm protocol, ownership rules, permission scopes, cascade side effects, irreversibility, and id sources — nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on top: owned:true is for assets 'you did not create' and triggers an app-connection consent, confirm:true only deletes after the user has seen the report, and deleteReleases is scoped to non-live UNPINNED releases. It stops short of restating deleteReleases' full mechanics, which the schema already carries.

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

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

The opening names a specific verb (Delete) and enumerates the exact resources it handles (images, models, audio, Blender models, texture sets), including edge semantics like 'kind blender: a whole uploaded .blend with every version'. It also names the sibling list tools that supply ids, so an agent can distinguish it from the r3_*_list readers without opening a schema.

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

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

Explicitly states when to use it (two calls, confirm only when the user wants deletion) and when not to (an asset another user's project uses 'can never be deleted'; owned:true only when the user asked). It names the alternatives for obtaining ids (r3_image_list, r3_audio_list, r3_blender_list) and the permission scopes gating each path.

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

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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true), and the description adds genuinely new context: the cross-tenant consequence of public:true (every R3 member can see and reuse the asset), the undo semantics, the cascade rule that a texture set is toggled with all its maps, and the required 'asset:share' scope. The undo note is consistent with idempotentHint rather than contradicting destructiveHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and scope are front-loaded in the first clause, and the undo path plus the texture-set cascade follow logically. The paragraph is dense with colon- and semicolon-chained clauses, which is efficient but slightly harder to scan than it needs to be.

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

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

For a 3-required-param toggle with full annotation coverage and an output schema, the description supplies everything an agent still needs: permission scope, reversibility, cascade behavior, id provenance, and boundaries versus out-of-scope asset types. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining that a textureSet id is the setId and that individual maps cannot be toggled, plus where ids originate. It does not add much on 'public' beyond what the schema already says, so it stops short of a 5.

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

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

States a specific reversible verb pair (show / hide), the exact resource types (images, audio files, texture sets), and scopes it to the user's OWN assets. It also distinguishes itself from sibling mutations by mapping to the in-app 'Show in Community' switch and by naming what is not covered (videos, Blender models, projects).

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

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

Explicit when-to-use constraint ('Use it only when the user asked to share or hide that asset'), explicit undo path ('call this tool again with public: false'), and explicit routing for ids ('Ids come from r3_image_list, r3_audio_list and r3_texture_read / r3_texture_create'). It also carves out the out-of-scope asset types and points to the R3 app for them.

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

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

Annotations already cover read-only/idempotent/open-world safety. The description adds real behavioral context the annotations cannot: the scan 'can take several seconds' (latency), totals always cover everything regardless of limit, and grouping rules (a model carries the images only it uses, a textureSet is one item containing its maps). No permissions/auth notes, so not a full 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Inclusion rule is front-loaded, then grouping, then exclusions, then params and sibling routing. Dense and information-rich, though a few clauses (the texture-set/map digression) could be tightened without losing meaning.

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

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

Output schema exists, so return values need no prose. Combined with annotations and a fully described schema, the description covers everything an agent needs: inclusion/exclusion rules, grouping semantics, latency, param effects and the correct sibling for deletion.

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

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

Schema coverage is 100% (baseline 3), and the description adds a non-obvious semantic: `limit` widens rows but the totals always cover everything, so the agent knows limiting does not truncate the aggregate. `kind`'s role is restated but not enriched beyond the enum.

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

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

States a concrete verb+resource with scope: 'the account's images, models and audio files that nothing uses'. It defines 'unused' precisely (no project, no entity template, no other user's project) and explicitly distinguishes itself from siblings r3_asset_delete, r3_blender_list, r3_image_list and r3_audio_list.

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

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

Explicit routing: use this to see what is unused, use r3_asset_delete to remove an item (with plan-then-confirm), use r3_blender_list for .blend files that are excluded here. Both the when and the when-not are stated.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description does not need to repeat that. It adds meaningful context beyond the annotations: the returned URL is directly assignable to R3ComponentAudio.url, search is matched server-side against every file rather than the current page, and uploads are impossible from this tool. It doesn't discuss rate limits or result ordering, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and the key URL detail, then follows with search guidance and limitations. Slightly verbose in the upload explanation ('a tool argument is JSON, this server cannot read your disk, and audio is megabytes'), but every paragraph serves a real agent need.

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

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

With an output schema present, the description needn't explain return values. It covers the full workflow an agent needs—find by search, get a URL, assign via r3_component_set—and rules out the wrong assumption that this tool can upload. Minor gaps (ordering, pagination mechanics beyond cursor) are already handled by the schema.

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

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

Schema coverage is 100%, so limit, cursor, and search are already documented in the schema, including that search matches on the server. The description reinforces search semantics with an example ('kick') and clarifies it isn't page-local, but this is a modest addition over the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the audio files this R3 account owns') and immediately says what each item carries (the URL usable as R3ComponentAudio.url). It is clearly distinguishable from siblings like r3_sound_create, r3_image_list, and r3_component_set.

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

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

Gives explicit when-to-use guidance: find a sound the account already has and point an Audio component at it via r3_component_set. It also explains search-vs-paging, states the upload limitation, and names r3_sound_create and R3 music components as the alternatives for making new audio.

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

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

Beyond the readOnlyHint and non-destructive annotations, the description explicitly says it changes nothing and that choosing which copy stays is the user's decision. It also discloses the exact deletion path, including the required bundle confirm token, which gives the agent critical 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core question and is generally tight. The quoted answer template is slightly cryptic but earns its place by showing what the tool returns.

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

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

Given an output schema exists, return values need not be fully explained, and the annotations cover the safety profile. The description still adds the key next-step workflow and non-mutation guarantee, leaving nothing important missing for correct invocation.

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

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

Schema coverage is 100%, so both projectId and blenderModelId are already documented in the input schema. The description does not add meaning beyond the schema for these parameters, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: it determines whether a project holds the same Blender model imported more than once. The 'two whole imports side by side' phrasing distinguishes duplicate detection from nearby siblings such as r3_blender_list or r3_blender_import.

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

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

The description makes clear this is a pre-deletion duplicate check and names the follow-up deletion tool with its required arguments. It does not explicitly say when not to use it versus listing tools like r3_blender_list, but the context is sufficiently unambiguous for selection.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, non-idempotent), and the description adds genuinely new operational detail beyond them: a one-time download ticket valid for 5 minutes, the returned endpoint (URL, method, Authorization header), and that the response body is the file itself. It also discloses the modifier-copy edge case and how to recover the original.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and ownership constraint are front-loaded, and every sentence carries information (version selection, ticket mechanics, modifier nuance). It is somewhat dense with nested clauses, but nothing is filler.

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

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

Covers everything an agent needs: ownership scope, version selection, the ephemeral ticket and auth requirements, and the modifier-copy gotcha. An output schema exists, so return-value explanation is not required, and the description still usefully describes the answer shape.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the conceptual distinction that fileId selects a specific version (or the original of an applied copy) while omitting it yields the current version. This meaningfully reinforces how the two parameters interact, though the schema already documents the sha256 format.

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

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

States a precise verb+resource: getting a .blend file of the user's OWN Blender model, selectable by current version or version fileId. It names r3_blender_list as the source of model IDs and distinguishes itself from sibling write tools (r3_blender_upload, r3_blender_import) by scoping to download only.

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

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

Gives clear context (to open in Blender, IDs come from r3_blender_list) and a real exclusion: another user's model cannot be downloaded. It even routes the agent to download the original upload instead when the current version is an applied-modifier copy. It stops short of naming a distinct alternative tool or a when-not-to-use scenario beyond the ownership limit.

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

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

Annotations cover the safety profile, but the description goes well beyond them: one draft per user, newest-wins, 24-hour retention, 20 MB limit, required blender:upload right, and a one-time ticket (5-minute) plus endpoint/auth mechanics. It also clarifies the copy is modifiers-applied and textures-packed, which matters for what the user sees.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core behavior and each clause carries real information. It is dense and slightly run-on with parenthetical ticket/endpoint detail, but there is little waste.

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

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

Covers retention, size limit, auth requirements, the ticket/endpoint delivery, and the contrast with the save path. With an output schema present, return values need not be described, so the definition is complete for correct invocation.

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

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

Schema coverage is 100% and the single 'model' parameter is already fully documented in the schema, so the description carries no additional parameter meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (push an applied copy of the working .blend as a draft) and immediately distinguishes it from the sibling r3_blender_upload, which 'saves the real file.' An agent can tell exactly what this does and how it differs from the nearest alternative.

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

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

Explicitly states when to invoke it ('after each step: body done, wheels done, materials done') and when the sibling is the right choice instead ('r3_blender_upload saves the real file once the user is happy'). Nothing 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.

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

Annotations flag a non-readonly, non-idempotent, open-world mutation; the description goes well beyond them by explaining the object-to-entity mapping, mesh/geometry sharing, root Empty behavior, the entityRef report, the camera refusal semantics, and reparse's cost ('Slow... re-parses and re-optimises every texture'). The one gap is what a repeated import of the same model does, which matters given idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then supporting semantics; nearly every clause carries decision-relevant information. It is dense to the point of being one long block, and the mesh/Empty mapping detail is the least essential part, but nothing is redundant filler.

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

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

With an output schema present, return values (entityRef per object) need not be spelled out further, and the annotations carry the safety profile. The definition covers mutation effects, failure modes, and prerequisites, leaving only the repeated-import/idempotency question unresolved.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by tying meshes to per-object placement and by giving a concrete trigger for reparse ('when the import warns that its meshes were placed at the origin') rather than restating the schema. It does not add syntax detail beyond what the schema already documents.

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

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

States a specific verb and resource: adds/imports an uploaded Blender model's current version into an existing R3 project, with optional mesh-level scoping. It is clearly distinguishable from r3_blender_upload (which supplies the model) and r3_blender_update (which moves meshes), both of which it names.

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

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

Explicit routing: 'Use r3_blender_list to choose a model', r3_blender_update 'moves them, if the user wants', reparse only 'when the import warns that its meshes were placed at the origin', and camera only for a NEW project's first model. Exclusions are stated, not implied.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses what each result carries (object/mesh/material counts, screenshot, pending-update flag), how R3 applies unapplied modifiers per object, the meaning of a PENDING update, and the important constraint that the upload ticket/endpoint is never a tool argument.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in the first sentence and every clause is informative, but it is a dense run-on paragraph that partly duplicates the output schema's field list, so it is slightly over-packed rather than maximally tight.

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

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

For a read-only list tool with an output schema present, the description covers scope, entry contents, pagination-adjacent behavior, the community toggle, and how models arrive — everything the agent needs to call it correctly.

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

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

Schema coverage is 100%, so the schema documents limit, cursor, search, and community. The description restates community's public-model behavior but adds nothing beyond the schema on limit, cursor, or search, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the Blender models this R3 account has uploaded') with scope and unit of return ('one per .blend file name, the current version of each'). It distinguishes itself from r3_blender_upload, r3_blender_update, and r3_blender_import by naming each and its role.

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

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

Gives clear context for use and routes the agent to siblings: models get here via the R3 app or r3_blender_upload, pending updates wait for r3_blender_update, and adding to a project uses r3_blender_import. It lacks an explicit 'use this instead of X when Y' exclusion, so it falls just short of a 5.

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

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

The description adds substantial behavioral detail beyond the annotations: it explains matching by Blender OBJECT name, material-preservation rules, handling of new and gone parts, removeGone semantics, and the required blender:update right. It is consistent with destructiveHint=true and readOnlyHint=false by clearly describing the plan as read-only and execution as mutating.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense but well-structured paragraph that front-loads the core model-update concept and then layers usage, matching behavior, and authorization details. Every sentence contributes operational context for a complex destructive tool.

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

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

Given six parameters, a destructive annotation profile, an output schema, and a nontrivial Blender-to-project update workflow, the description covers planning, execution, matching semantics, material handling, removal behavior, and permissions. No additional explanatory sentence is needed for an agent to invoke it correctly.

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

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

Although schema coverage is 100%, the description meaningfully explains the conditional relationship between parameters: choice without reportId plans, while reportId plus projectIds/entityTemplateIds executes. It also clarifies removeGone's effect and the choice between planning and answering a report.

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

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

The description states a precise verb and resource (update projects to a Blender model's current version) and immediately distinguishes its planning mode from its execution mode. It also distinguishes the tool's scope from other Blender tools by explaining that published releases never change and that it only moves selected projects/entity templates.

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

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

It gives explicit when-to-use guidance: call without reportId to produce a plan, call with reportId and selected IDs to apply changes, and make no call for 'not now'. It also states that published releases are unaffected, removing ambiguity about scope.

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

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

Beyond the annotations, it discloses a one-time 5-minute upload ticket, the endpoint URL/method/Authorization header and raw-bytes body, the need for file access, the 100 MB limit, the required blender:upload right, and the packed-texture caveat. These are exactly the behavioral details an agent needs and are consistent with openWorldHint=true, idempotentHint=false, and destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and nearly every sentence carries operational value, including ticket handling, file access, size limit, rights, and follow-up tools. It is dense and somewhat run-on, but the length is justified by the complexity of the upload workflow.

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

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

Given a one-parameter but multi-step upload workflow with annotations and an output schema, the description covers prerequisites, ticket/endpoint mechanics, file-access alternatives, size limits, rights, texture packing, and follow-up tools. Nothing essential for correct invocation appears to be missing.

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

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

The single fileName parameter is fully documented in the schema, including the 'name only, no folder' constraint and the automatic .blend suffix. The description reinforces the model-naming consequence but adds little beyond the schema, so the high schema coverage sets the baseline at 3.

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

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

The description states a specific action (save a .blend) and resource (newest version of a Blender model), and explains the naming convention that links the file to the model. It is easily distinguishable from siblings like r3_blender_import and r3_blender_update because it describes the upload/versioning step.

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

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

It gives explicit conditions for use: after making or changing a .blend in Blender or a Blender MCP, and it names the fallback when file access is unavailable (user uploads on the Blender page). It also routes the agent to r3_blender_update for an older-version question and to r3_blender_import for placing the model in a project.

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

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

Annotations only declare write/open-world/non-idempotent; the description adds the substantive behavior: the report becomes a private support issue visible only to the user and R3's team, it is rate-limited per agent key or app connection (a few an hour), it requires the support:write right, the response carries a shareable link, and r3_bug_reports_mine exists to avoid duplicates. That is exactly the context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and identity in the first sentence, then routing/exclusions, then operational detail. The paragraph is dense and long, but each sentence carries a distinct constraint (docs check, dedup, measurements, visibility, rate limit, auth) rather than padding.

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

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

For a 4-param submission tool with an output schema already covering the return shape, the description supplies everything else an agent needs: prerequisites, exclusions, auth right, rate limit, visibility, dedup path, and expected report content. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `measurements` should carry values read back with r3_component_read or r3_editor_inspect plus exact error text, and `projectId` is what lets R3 open the case. It also prescribes report content (what was done, expected, happened) beyond the terse schema phrasing.

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

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

States a specific verb and resource: send a bug report about R3 ITSELF (engine, editor, these tools), filed in the user's name. It explicitly scopes the subject away from the user's own project and from feature requests, so an agent can separate it from r3_roadmap_suggest or a project-level issue without opening any schema.

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

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

Gives the trigger condition ('when R3 does something its documentation says it should not'), a prerequisite ('after checking the docs (r3_docs_read)'), two explicit exclusions ('not for problems in the user's own project, and not for feature wishes'), and names the sibling to use instead for wishes (r3_roadmap_suggest). Nothing 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.

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds two things annotations cannot: the required 'support:write' right for a read-oriented tool, and the contents/ordering of results (status, date, project, agent-attribution, link, newest first). It stops short of pagination or rate-limit detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the resource and scope before the alternative-tool routing. The parentheticals (agent keys/app connections, which agent) are dense but each carries a real qualifier; the phrasing around the duplicate-filing point is slightly indirect but earns its place.

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

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

An output schema exists, so return values need not be described, yet the description characterizes them anyway alongside the auth requirement and default ordering. Combined with the safety annotations, an agent has what it needs to call this correctly; only pagination/large-result behavior is unaddressed.

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

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

With a single parameter at 100% schema description coverage, the schema already documents 'limit' including its default and maximum. The description mentions ordering but adds nothing about the limit, paging, or what happens when more than 100 exist, so it neither compensates nor detracts.

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

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

The description names a specific resource (the user's own support issues, including bug reports and questions filed via agent keys/app connections) and states the ordering (newest first). It explicitly distinguishes itself from the sibling that files reports, r3_bug_report, so an agent can route between the two without opening either schema.

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

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

It gives an explicit usage condition — check here first to see whether a fault is already reported — and names the alternative tool (r3_bug_report) that the agent would otherwise call and duplicate. This is the when-to-use/when-to-prefer-a-sibling guidance the dimension asks for.

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

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

Annotations already declare the safe read-only, idempotent profile, but the description adds real behavioral detail beyond them: oversized bodies are omitted WHOLE with their size reported and never truncated, with the reason given (a partial write-back would delete the rest). It also specifies that an invalid entityRef is named while the other refs are still read — non-obvious partial-failure semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then usage, then edge-case behavior; every sentence carries operational information and none is filler. The four-paragraph shape is slightly longer than strictly required for a two-parameter tool, which keeps it just short of top marks.

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

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

An output schema exists so return values need no restatement, yet the description still supplies the two things the schema cannot: how to chain codeVersion back into r3_code_write and why truncated bodies are impossible. Combined with the fallback enumeration path and partial-failure behavior, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: omitting entityRefs is framed as the way to enumerate every Code component and to recover a missing ref. It also explains that the returned codeVersion feeds r3_code_write's baseVersion and that the event returns as a NAME in write-compatible form.

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

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

States a specific verb and resource ('Read back what a Code component actually contains — its full JavaScript source and the event it runs on') and immediately contrasts itself with r3_code_write ('reports what it wrote; this reports what is there'). It also draws a firm line against the same-purpose sibling r3_component_read, so an agent can select correctly without opening any schema.

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

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

Gives explicit when-to-use cases: before replacing a script so an edit builds on the real source, and after a write whose reply was not seen, to confirm what landed. It names alternatives (r3_code_write for writing, r3_component_read for shallow reads) and states the no-entityRefs fallback for recovering a lost entityRef.

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

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

Annotations declare destructive=true and readOnly=false, and the description goes well beyond them: it discloses that code lives in the live copy every open tab runs with nothing to save, that dispose is called on re-save/Stop/delete, that writes on an older version are refused with the current code and never merged, and that disallowed APIs (getComponentByRef, this.state, this.getSibling, R3 global) cause the code to be REFUSED. These are exactly the side effects an agent needs to avoid silent corruption.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose, constraints and the code contract are front-loaded, and the worked JS example is high-value. It loses a point for duplication: the full event list appears in both the description and the `event` schema property, and the infra-method list is dense prose that could be compressed.

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

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

Output schema exists, and the description still adds the key return facts (seq and codeVersion). For a 7-parameter, destructive, event-driven write tool it covers execution model, versioning, cleanup obligations, and refusal conditions — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the shape of `code` (a function body that must `return {start, update}` or nothing runs), the create-vs-replace semantics of name/entityRef, and the versioning contract for baseVersion. It does not add much beyond the schema for event/componentId, which keeps it from a 5.

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

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

Opens with a specific verb+resource ("Add or replace a Code component: JavaScript that makes a project DO something") and immediately distinguishes itself from siblings by noting that r3_editor_code is the same tool. An agent can tell what it produces and which event-driven execution model applies without opening any schema.

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

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

Explicit routing: pass entityRef + baseVersion to REPLACE, name (or neither) to CREATE, and read baseVersion from r3_code_read first. It also points to r3_docs_read("HOWTO_CODE_EVENTS.md") and CODE_PATTERNS.md for the event table and API, and names the alternative alias r3_editor_code. When-to-use and when-not (mutually exclusive name/entityRef) are both stated.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), it discloses real behavioral traits: the component is kept immediately in the project's live copy and visible in every open tab with nothing to save, unknown types are refused with the type list, types requiring a mandatory option are refused without it, and mesh-linked components are auto-fitted only for values not passed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded, but the body is a long run-on sentence dense with em-dash and parenthetical asides (VehicleWheel/Configure from Mesh, Fit to Mesh, PHYSICS_USAGE.md) that make it hard to scan. The content largely earns its place given the tool's edge cases, but the packaging is heavy and under-structured.

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

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

An output schema exists, so return values need not be documented, yet the description still notes 'the answer says what' was auto-fitted. For a 3-parameter mutation tool with nested open-object values, it covers the type format, the value/reference encodings, mandatory-option types, and Code component ownership, leaving no obvious gap.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema does not: `type` is the short type name and unknown values are rejected with a list, and `values` may be a plain value, a value component, or a reference expressed as the target's entityRef or id, with 'name' naming the component. The exact shape vocabulary is still delegated to r3_component_set rather than defined here.

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

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

The first sentence gives a specific verb (add) and resource (component) plus the broad scope ('ANY registered type'), then enumerates examples (collider, rigid body, joint, light, material, geometry). It actively distinguishes itself from siblings by noting r3_editor_add_component is the same tool and routing ready-made objects to r3_factory_run.

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

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

It names an alternative with its selecting condition ('Use r3_factory_run for a ready-made object (a cube, a physics sphere …)') and aliases r3_editor_add_component, which is genuinely useful routing. However it gives no explicit when-not-to-use guidance and never contrasts against the closely related r3_component_set, leaving that boundary to be inferred.

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

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

Annotations already declare read-only, idempotent, non-destructive, but the description adds real context: it works with no R3 tab open against the stored project, batches up to 20 entities, and returns each child part of a hierarchy. It stops short of discussing failure modes (e.g. unknown entityRef) or result ordering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: the output shape comes first, then accepted inputs, then usage recipes, then constraints (20 per call, no tab needed, read-only). A few parentheticals stack up, but every sentence carries information an agent needs.

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

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

An output schema exists, yet the description still summarises the payload (box, parts, camera framing), names the project source of truth, and states batch limits and the no-tab requirement. An agent can call this correctly without consulting anything else.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning beyond the schema: entityRefs may be a Mesh or the root Empty of an imported model (named "<model>_root" by r3_blender_import), and the measured box aggregates the whole subtree. That clarifies accepted input values rather than just repeating types.

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

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

States a specific verb (measure) and resource (meshes and imported models) and enumerates exactly what the result contains: world-space box min/max/size/centre, scale, rotation and parents applied. It is clearly distinguishable from siblings like r3_component_read or r3_terrain_height.

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

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

Gives explicit when-to-use drivers (before scaling or placing anything relative to its size) plus concrete recipes: move so min.y equals ground height using r3_terrain_height, or scale by 2 / size for a 2 m model. It also names the companion use case of framing a model via the returned camera position/lookAt.

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

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

Read-only and idempotent are already covered by annotations, but the description adds real behavioural detail the annotations cannot: bulk vertex arrays are deliberately excluded and every omission is reported with a reason, and a nonexistent entityRef is reported by name while the rest still resolve. It also documents the return-value shape (expanded inline values, entityRef strings, null for empty references, arrays for reference lists). It stops short of stating pagination/ordering or how the 50-item cap failure surfaces.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and organised into short, scannable paragraphs, each addressing a distinct question (batching, return shape, omissions, errors). It is longer than most tool descriptions and the final note on value components could be tighter, but no paragraph is redundant.

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

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

For a read tool with an output schema and full annotation coverage, this is complete: it covers what is returned, what is intentionally withheld and how that is signalled, partial-failure behaviour, and the relationship to the write counterpart. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds genuine selection semantics beyond the schema: it tells the agent that multiple entityRefs should be preferred in one call, and that the singular entityRef form is an equivalent shorthand for a single component — a distinction the schema text alone leaves thin.

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

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

States a specific verb+resource with scope: read back the values components hold (colour, roughness, position, material reference). It explicitly contrasts with r3_project_load ("gives you the names; this gives you the values behind them") and with r3_component_set, so the agent can slot it into the read/modify/write cycle without opening a schema.

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

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

Gives concrete when-to-use cases (use before any relative change like "20% brighter"; use after a write to confirm what landed) and an explicit batching recommendation with the scenario it serves (telling six similarly-named materials apart). It also names the sibling to use for name discovery, so alternatives and exclusions are both present.

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

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

Goes far beyond the destructive/non-idempotent annotations: immediate live sync with nothing to save, all-or-nothing multi-property application, typo refusal with valid names listed, physics derivation rules (VehicleWheel measuring, Collider fitting), collider re-fitting on mesh scale, suspension carry-over on chassis scale, and re-parent world-preservation with a shear refusal case. This is exactly the extra context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and live-sync behavior, then organized with bullets for the four value shapes. The length is largely earned by genuine behavioral complexity, though the repeated "The answer says/lists…" phrasing and the live-copy sentence could be tightened.

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

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

An output schema exists, yet the description still summarizes what comes back (what was kept and its seq, list before/after). Given the unconstrained properties bag and the many derived side effects, this is complete enough for an agent to call the tool correctly without opening the editor docs.

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

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

Schema coverage is 100% for the declared parameters, but `properties` is an unconstrained bag whose contents the schema cannot describe. The description supplies the missing semantics in full: the four value shapes, partial-key objects for value components, empty-slot construction, entityRef strings vs. arrays, and the replace-not-append list rule with [] emptying.

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

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

States a specific verb (set properties) on a specific resource (a component that already exists in a project), with concrete examples (material roughness, mesh position, which material a mesh uses). It explicitly distinguishes itself from r3_editor_set ("the same tool") and implicitly from r3_component_add by scoping to components that already exist.

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

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

Clear context for use (existing component, live project) and explicit when-nots: unknown property names and renames are refused, with renaming routed to the R3 editor. It never explicitly names r3_component_add as the path for creating a new component, leaving that 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.

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered structurally. The description adds the reading-order and content/size disclosure, but says nothing about side effects, auth, or limits beyond the annotations, and return content is likely already in the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and scope, then two supporting sentences. The middle sentence is motivational rather than operational, which is slightly at odds with strict economy, but it justifies why the tool exists and earns its place.

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

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

With an output schema present, return format needn't be re-explained, and the description covers purpose, ordering, and sibling routing. Nothing an agent needs to invoke this zero-param list tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. No parameter semantics are claimed or needed.

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

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

States a specific verb+resource ('Every R3 document... list') with scope detail ('IN READING ORDER, with what each one covers and how big it is'). It explicitly differentiates from the sibling by noting 'r3_docs_read returns one', so an agent can route between the two without opening either schema.

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

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

Frames this as the entry point ('R3's documentation begins here') and names the alternative r3_docs_read with its single-document behavior, implying list-first then read-one. There is no explicit when-not or exclusion, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent and closed-world, so safety is covered. The description adds genuinely new behavior: the API reference can only be read one symbol at a time because the whole file is too large to serve, which prevents a futile bulk-read attempt. It does not say what happens on an invalid or stale path, so it stops short of 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core statement and constraint are front-loaded, and each example line earns its place by mapping a path to its content. The table-style indentation is slightly awkward in a plain description and the 'reading order 1' aside is terse, keeping it just below top marks.

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

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

For a single-parameter, read-only docs tool with no output schema, everything needed is present: what is returned, how paths are formed, where to get them, and the one-symbol-per-call limit on API reads.

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

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

Schema coverage is 100% and already gives examples, but the description goes further by enumerating the api/component, api/system and api/event path shapes and what each returns, which the schema does not. This is real added semantic value for constructing a valid path.

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

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

States a specific verb and resource: 'Return one R3 document in full, or one API symbol.' It immediately distinguishes itself from the sibling r3_docs_list, which only supplies paths, and from r3_code_read by being documentation rather than source.

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

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

Explicitly routes the agent to r3_docs_list as the source of paths and to r3_docs_list again for how-tos, and even notes a reading order for CODE_PATTERNS.md. The condition for choosing a doc path versus an api/ symbol path is spelled out in the examples.

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

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

Annotations only provide safety hints; the description adds the crucial live-sync semantics: the component is kept at once in the project's live copy, every open R3 tab shows it immediately, and nothing needs saving. It also discloses the failure mode for unknown types (refused with the list) and that references must resolve to a component in THIS project of an accepted type.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the alias identity and live behavior, then parameters, then an example. Slightly dense with backtick-heavy inline detail, but every sentence carries actionable information.

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

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

With an output schema present, return values need not be described. The description covers alias identity, live propagation behavior, type/value/reference syntax, refusal behavior, and the follow-up sibling call — complete for a 3-param mutation tool.

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

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

Schema coverage is 100% (baseline 3), but the description genuinely adds meaning: `type` is the short type name with examples, and `values` accepts three distinct shapes — plain values, value components given as keys to set, and references as entityRef or id. That is detail the schema's free-form object cannot convey.

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

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

States a specific verb (add) and resource (one component of ANY registered type) and explicitly identifies the alias relationship to r3_component_add. It distinguishes itself from siblings r3_editor_create (ready-made object) and r3_component_set (values shapes), so an agent can route correctly.

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

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

Names the alternative (r3_editor_create) and the condition that selects it, and gives an end-to-end example workflow (add ColliderCuboid with rigidBody/halfExtents references, then r3_editor_delete in mode "one"). Explicit when-to-use plus a concrete chained scenario.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing the return type (an image, JPEG), the resolution ceiling (1280 px each way), the default camera semantics, and the project:read permission requirement. That is exactly the kind of context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and outcome, then branches into usage and camera modes. Dense and mostly waste-free, though the parenthetical asides and repeated camera explanations make it longer than strictly necessary.

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

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

With an output schema present, the description need not explain return values, yet it still signals that the answer is an image. Auth needs, default resolution, camera modes, and sequencing with sibling editor tools are all covered, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds practical meaning: the default behavior of camera:'editor' (user's view, edit aids included) versus 'project' (visitor's view, no edit aids) and the output format/size implications of width. It slightly exceeds what the schema alone conveys.

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

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

States a specific verb (capture) and resource (the canvas of a project open in the user's R3 editor) with a clear qualifier ('the scene as it looks NOW, running physics included'). It distinguishes itself from siblings like r3_image_create or r3_preview_create by scoping to the live editor viewport.

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

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

Explicitly names the trigger conditions and the sibling tools that precede it: call after a visual change (r3_editor_set, r3_editor_create, r3_editor_code) and after r3_editor_run to see motion. It also gives a targeted use case for the camera:'project' variant (checking a camera or camera script), leaving little to inference.

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

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

Annotations already flag destructive/openWorld, and the description adds substantial context beyond them: changes apply immediately to all open tabs, code is never merged, a stale baseVersion is refused with the current code and version, and syntax/unknown-API errors are rejected before anything is persisted. This atomicity and conflict-handling detail is exactly the behavioral disclosure the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and most clauses earn their place (conflict handling, function-body format, doc reference). It is a dense run-on sentence with some parenthetical redundancy around the r3_code_write alias, but no filler.

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

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

With an output schema present, return values need no explanation, and the description still covers naming, versioning, code format, error/refusal behavior, and live semantics. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it explains the componentId/entityRef alternative naming, why baseVersion is required (the version the code builds on), and null for never-saved components. Minor inconsistency: it attributes the codeVersion to r3_code_read while the schema cites r3_editor_inspect.

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

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

States a specific verb (replace a Code component's code) and resource, plus the exact effect (runs live in every open R3 tab). It explicitly names r3_code_write as the same/older name and r3_code_read as the version source, so an agent can disambiguate from siblings.

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

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

Gives clear context (live application, no editor/save needed) and routes to r3_code_read for the version and r3_docs_read("CODE_PATTERNS.md") for APIs. It does not, however, state when *not* to use it versus r3_code_write or the non-live code path.

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

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

Annotations already declare readOnly=false, destructive=false, openWorld=true, idempotent=false, so the safety profile is covered. The description adds genuinely new behavioral context: the change is applied immediately, propagates to every R3 tab with the project open, and requires no save step. It does not address calling it twice with the same name (relevant given idempotentHint=false) or whether r3_editor_undo can reverse it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A compact two-sentence description with the important live/immediate behavior front-loaded after the alias note. The parenthetical '(this is its older name)' and the trailing factory-list pointer are both useful, though the em-dash/ellipsis phrasing makes the core sentence denser than necessary.

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

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

For a live-mutation tool with a nested params object and an output schema (so return values need no prose), the description covers what the agent needs: what gets created, that it appears immediately everywhere, and where to get valid factory names. Only edge-case behavior — duplicate names or undoability — is absent.

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

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

Schema description coverage is 100%, so all four parameters (name, params, factory, projectId) are already documented with examples and units (radians, packed RGB int). The description only reinforces this by pointing at r3_factory_list for the factory enumeration; it adds no format or constraint detail beyond what the schema supplies, so the baseline 3 applies.

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

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

States a concrete verb and resource ('add an object — a cube, sphere, light, physics body') plus the key scope fact that the object lands in the project's live copy. It explicitly identifies itself as the older name of r3_factory_run, so an agent knows the two are interchangeable, and points at r3_factory_list for the factory vocabulary. It does not distinguish itself from other add-style siblings such as r3_editor_add_component or r3_component_add, which is the remaining ambiguity.

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

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

Usage is implied rather than stated: 'no editor needed and nothing to save' tells the agent this takes effect immediately, and r3_factory_list is named as the prerequisite lookup for factory names. There is no explicit when-to-use / when-not guidance and no statement about how this differs from r3_editor_add_component, leaving the agent to infer the boundary.

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

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

Annotations declare destructiveHint=true/idempotentHint=false, but the description adds substantial behavior the annotations cannot: the two-call plan/confirm protocol, that the first call changes nothing, that a stale project refuses the confirm, that the delete is instantly visible in every open tab, that items go to project trash, that Empty/Mesh children retain world position, and the required editor:dispose capability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the essential two-call concept and dense with decision-relevant detail, but noticeably long with some redundancy (repeated emphasis on the plan/confirm flow and modes). Each sentence carries information, so it is efficient rather than padded, though it could be tightened.

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

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

For a destructive, capability-gated, multi-phase tool it covers the full call contract, side effects, failure mode, and capability requirement; output schema exists so return values need not be restated, and it still notes 'the answer lists them' for child handling. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra by explaining what the enum modes actually do ('one' vs 'with_dependents' vs 'bundle'), which the schema only names, and by describing planToken provenance and the confirm-vs-omit contract. This adds operational meaning beyond the schema fields.

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

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

States a specific verb (delete) and resource (components from the project currently OPEN in the R3 editor), and explicitly excludes a nearby confusion: 'A project itself is never deleted here,' which separates it from r3_project_delete and r3_asset_delete. An agent can identify it without opening the schema.

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

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

Gives a clear when ('Only when the user asked for it'), a when-not ('A project itself is never deleted here'), and the mode-selection rule ('The mode is the user's choice, unless they already said'). It stops short of naming sibling tools to prefer for adjacent tasks (e.g. r3_editor_undo, r3_asset_delete), so it is strong but not fully explicit about alternatives.

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

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

Beyond the annotations, it discloses that runtime values are included (a moving body's position while the project runs), that a limit of 50 components per call exists and larger answers are refused with narrowing guidance, and that output shape matches r3_component_read so results can feed r3_component_set. readOnlyHint/destructiveHint are reinforced by 'Read-only: nothing is changed', and the changing live values are consistent with idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the live-value distinction, then parameters then constraints. Slightly redundant: the 'project must be open in the editor (r3_editor_open opens it)' requirement is stated twice, once early and once at the end.

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

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

An output schema exists, so return values need not be described, and the description still flags the output shape and its compatibility with r3_component_set. Prerequisite, limits, filtering semantics, and read-only nature are all covered — nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not encode — that ids, type, and entityRef 'combine' (conjunctive filtering) and that fields keeps only the named properties. Examples for fields and type types align with the schema rather than duplicating it verbatim.

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

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

States a precise verb+resource+scope: reading live/runtime component values from a project open in an R3 editor tab. It explicitly contrasts with the nearest siblings, r3_component_read ('kept values without a tab') and r3_editor_open (opens the tab), so an agent can route without opening schemas.

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

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

Gives the when ('use it to debug live behaviour'), the prerequisite ('needs a tab with the project open'), the tool that satisfies that prerequisite, and the alternative (r3_component_read) with the condition that selects it. Nothing 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.

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real behavior beyond them: an already-open project is focused and never reloaded, the editor refuses at 4 projects, nothing is saved or changed, and the no-editor case returns guidance on where to open one. These are concrete operational traits an agent cannot infer from the hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and its focus-vs-reload nuance; the second paragraph groups access rules, capacity limit, and no-side-effect guarantees. Slightly dense in places (the r3_editor_inspect aside), but every sentence carries information.

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

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

An output schema exists so return values need not be described, and the description still covers the non-obvious cases an agent must handle: nothing persisted, capacity refusal, and the no-open-editor fallback. Complete for a single-parameter tool.

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

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

Schema coverage is 100% and the projectId property already names its sources (r3_project_list / r3_project_create). The description adds no format, validation, or edge-case semantics for the parameter, so the baseline 3 is appropriate.

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

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

States a specific verb (open), resource (project), and target surface (the user's currently open R3 editor tab), with the exact behavior of focusing an already-open project. It implicitly distinguishes itself from r3_project_load and r3_editor_create by framing this as 'show the user' rather than load/create.

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

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

Explains the reason to call it (it is how the user sees the project, and it is the precondition that r3_editor_inspect reads against) and documents the access rules and the 4-project refusal limit. It does not explicitly exclude or compare against the closest sibling r3_project_load, so it stops short of full when-not guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds substantial context beyond them: nothing is persisted, a paused simulation resumes, the browser pauses background tabs so the response may report the scene is NOT advancing, and the editor:run right is required. This is exactly the extra behavioral content annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the verb and resource, and virtually every sentence carries distinct value (effect, workflow, persistence, tab caveat, permission). It is dense but not padded; the only minor cost is length and a few fragmentary asides like 'Needs the editor:run right.'

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

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

For a mutation-style tool with an output schema, the description still covers the things an agent needs: side-effect scope (nothing saved), permission requirement, tab-focus failure mode, resumption semantics, and the intended testing workflow. Nothing material is left to inference.

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

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

Schema coverage is 100% and both parameters are already documented in the schema, including the systems enum of subsystems. The description only restates the default ('all of them, or the ones named in systems') without adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific action (press Run in the user's open R3 editor) plus the exact subsystems affected (physics, code, audio, music). It is immediately distinguishable from r3_editor_stop and from the read-oriented siblings r3_editor_capture / r3_editor_inspect.

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

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

Gives an explicit when: 'Use it to TEST what you built', followed by a concrete workflow naming the follow-up tools (r3_editor_capture, r3_editor_inspect). It also supplies a conditional caveat (scene only advances while the tab is foregrounded). No explicit when-not against r3_editor_stop or r3_factory_run, so it stops short of a full 5.

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

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

Annotations already flag destructive=true, idempotent=false and openWorld=true, so the safety profile is covered. The description adds real behavioral context beyond that: all-or-nothing application, unknown names refused with the valid ones returned, live propagation across tabs, and the null-clears / list-replaces semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the identity and live-propagation point, then spends the rest on parameter shape detail, which is dense and mostly earns its place. The opening parenthetical about the older name is slightly redundant but sets up the sibling relationship.

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

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

For a destructive mutation with an output schema present and full annotation coverage, the description supplies the missing pieces: atomicity, null/list semantics, and code-change routing. It stops short of noting permission or session prerequisites, but the agent otherwise has enough to call it correctly.

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

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

Although schema coverage is 100%, the description goes well past the schema's thin 'What to set' note by enumerating every accepted values shape: plain value, value-component object, empty-slot construction, entityRef reference, null to clear, and array-of-refs which replaces the list. It also clarifies that componentId and entityRef are interchangeable identifiers.

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

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

States a specific verb and resource (change component properties) and pinpoints scope: the project's live copy, reflected in every open R3 tab. It also explicitly disambiguates from siblings, noting it is the older name for r3_component_set and deferring code changes to r3_editor_code.

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

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

Gives clear operating context ('live', 'no editor needed, nothing to save') and routes one case to an alternative, telling the agent that a Code component's code belongs to r3_editor_code. It does not, however, explain when to prefer this over its alias r3_component_set, which is a notable gap given it declares them identical.

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

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

Adds real context beyond annotations: it waits for textures to load, excludes edit aids (grid, gizmos, outlines), returns the picture it set, and notes a live page keeps its old share image until the next publish. The overwrite of a previously set share image (which underlies destructiveHint=true) is only implied, not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and every clause carries information, though the first sentence is a long chain of appositives that could be split for readability. No filler or restatement of the name.

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

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

An output schema exists, so return values need not be explained, and the description still covers timing, permissions, and publish coupling. The one missing piece is an explicit statement that an existing share image is replaced, which matters given the destructive annotation.

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

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

Schema coverage is 100% and the single projectId parameter is already documented as 'a project open in the user's editor'. The description only reinforces that an open editor tab is required, adding little beyond the schema.

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

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

States a specific verb and resource: use what the camera shows NOW in the open R3 editor as the project's share image, and names exactly where that image surfaces (live page, link previews, showcase). It distinguishes itself from r3_editor_capture (preview beforehand) and ties the result to r3_publish_live.

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

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

Gives explicit trigger conditions ('once the project looks right', 'when the user asks for a new picture') and names the alternative tool (r3_editor_capture) for checking the view first. The prerequisite of an open editor tab plus project:write is spelled out.

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

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

Annotations already declare non-readOnly, idempotent and non-destructive, and the description adds context those cannot carry: the physics side effect ('puts every body back where it was placed'), a persistence guarantee ('Changes nothing saved'), and an authorization requirement (editor:run right). It is consistent with, and strictly additive to, the annotation set.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the action, followed by scope, side effects, persistence and prerequisite in descending order of need. No sentence is redundant padding; the parenthetical qualifier on `systems` earns its space by clarifying the all-vs-named choice.

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

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

With an output schema present, return values need no explanation, and the annotations cover safety. The description supplies the remaining pieces an agent needs: permission requirement, scope selection, side effect on physics bodies, and the guarantee that nothing is persisted.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description restates the `systems` semantics ('all of them, or the ones named in `systems`') without adding new syntax, ordering or default behavior beyond what the schema and its enum-like value list provide. Baseline 3 applies.

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

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

States a specific verb ('Stop') and resource ('the user's open R3 editor'), enumerates exactly what gets stopped (physics, code, audio, music), and is unmistakably the inverse of the sibling r3_editor_run. An agent can tell what it does and what it does not do without opening the schema.

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

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

Gives a clear prerequisite ('Needs the editor:run right') and frames invocation as equivalent to the user's own Stop click, which tells the agent when calling it is appropriate. It never names r3_editor_run as the counterpart in an explicit 'to do X instead, use Y' form, so it stops short of full routing guidance.

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

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

Adds substantial behavior beyond annotations: it explains that all changes from one tool call are undone together, that the user sees the result immediately in open R3 tabs, that conflicting later changes are SKIPPED and dropped from history, and that redo is valid only until a new change is made. It also discloses required permissions (project:write and code:write for code changes), which annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and then covers edge cases in a logical order. It is slightly verbose and has some redundancy (e.g., repeating that it only affects the agent's own changes), but every sentence carries useful information for correct invocation.

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

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

Given the complexity of undo/redo with conflict handling, the description covers scope, skip behavior, redo validity, and permission requirements. An output schema exists so return values need not be explained, and annotations already declare the destructive/non-idempotent profile, making the definition complete for an agent to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters in detail. The description repeats 'newest first' for count and adds only the redo window ('until you make a new change') beyond what the schema provides, so it does not meaningfully extend parameter semantics.

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

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

States a specific verb and resource ('Undo the last change ... made to a project') and scopes it precisely to changes made by this agent key or app connection. It distinguishes itself from siblings like release rollback or project changes by explicitly limiting undo to the agent's own tool calls, so an agent can identify it without opening other schemas.

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

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

Gives clear when-to-use ('when your own change was wrong or the user asks you to take it back') and when-not-to-use ('It never undoes the user's changes or another agent's: only yours'). It does not name an alternative tool for undoing others' changes, so it falls short of the explicit alternatives criterion for a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and a closed-world scope, so the safety profile is covered. The description adds genuinely non-structural context: that each entry carries options, types and defaults, and what a 'factory' actually produces. It stops short of describing return shape or pagination, hence not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action and followed by usage guidance. The middle explanatory sentence about what a factory builds is slightly verbose but earns its place by grounding the term 'factory'.

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

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

With no output schema, the description usefully pre-announces that entries include options, types and defaults, and it covers both purpose and call timing. A little more on the returned structure would make it fully self-sufficient.

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

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

Schema description coverage is 100%, so the single optional 'factory' parameter is already fully documented with an example ('Cube'). The description mentions entries have options/types/defaults but adds no syntax or filtering detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (R3 factories), and names the sibling it serves (r3_factory_run) so it is immediately distinguishable from that tool. The additional clause about a factory producing a complete wired object makes the concept concrete rather than abstract.

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

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

Gives an explicit trigger: 'Call this before r3_factory_run if you are unsure of a factory name or its options.' It names the alternative tool and the exact condition that selects this one, leaving nothing to inference.

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

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

Goes well beyond the annotations: writes land in the project's live copy, every open R3 tab reflects the change immediately, nothing needs saving, and the response reports what was kept plus its seq. It also discloses the name-collision behavior (a reused name gets _2) and that renaming afterwards must happen in the R3 editor — consistent with destructiveHint=false and idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly — what it does, then the live-copy behavior, then naming — but it is a dense run-on paragraph that packs naming rules, live sync, and a multi-sentence StudioLighting tutorial together. The live-editing point is restated twice ("every R3 tab shows it now" / "no editor needed and nothing to save"), and the studio-lighting digression interrupts the flow.

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

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

For a mutating factory tool with four documented params and an output schema, nothing essential is missing: side effects on the live project are covered, naming/identity semantics are covered, option discovery is delegated to r3_factory_list, and return content is summarized rather than re-specified.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: how "name" propagates to entityRef and to derived geometry/material names, and that collisions are suffix-disambiguated. The lengthy StudioLighting passage effectively explains one factory's params (HDR environment + key light), though it is oddly placed and factory-specific rather than general.

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

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

States a specific verb and resource ("Add an object to an existing R3 project") plus the concrete object families (cube, sphere, terrain, lighting, physics body). It also distinguishes itself from the component-level siblings by explaining that factories produce fully-wired objects, and explicitly identifies r3_editor_create as the same tool.

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

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

Clear routing guidance: "Use r3_factory_list to see the factories and their options" for discovery, and "so you never assemble components by hand" implicitly steers away from r3_component_add/r3_editor_add_component. It never names those siblings explicitly as the alternative, so the exclusion is inferred rather than stated.

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

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

Goes well beyond the annotations by disclosing the replace-not-append semantics, the optimistic-concurrency rule that an older baseVersion is refused with the current text, and that the change is applied at once to the project's live copy. It does not discuss permissions or whether the write is undoable, so it stops just short of full behavioral coverage for a destructive mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five short paragraphs, purpose front-loaded and each block carrying distinct information. It is longer than strictly necessary and restates the baseVersion requirement that the schema also documents, but there is little filler.

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

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

For a destructive, non-idempotent write with an output schema, everything an agent needs is present: lifecycle of the single Help entity, concurrency handling, live-propagation behavior, and a pointer to the downstream tool that consumes the returned entityRef.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: why baseVersion exists and when to omit it, what the title does by default, and a concrete markdown format example for the body. The syntax-level detail the markdown parameter accepts is the main thing left to the schema.

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

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

"Set the instructions that ship WITH a project" is a specific verb and resource, and the description immediately distinguishes it from adjacent tools by noting a Code component "needs no overlay of its own" and that trigger/layout changes go to r3_component_set.

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

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

It states when to call (setting help text), when baseVersion is required vs. omitted (replace vs. first write), what happens on a stale version, and explicitly routes the agent elsewhere for trigger key/move/hide via r3_component_set.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive and open-world; the description adds real behavioural context beyond them: the 1MB decoded limit, accepted formats, PNG as the recommended choice, that each call creates a NEW row even with identical bytes, and that the name is surfaced to the owner with an 'agent-' prefix. This is exactly the kind of consequence-level detail annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and return value, then constraints, then exclusions/alternatives — a sensible order. It is on the long side at four paragraphs and repeats the 1MB/base64 point that the schema also states, but every remaining sentence carries information an agent needs.

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

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

An output schema exists and the description still names the returned value (the URL for R3ComponentTexture.url), so return semantics are covered. Limits, formats, naming side effects, non-idempotency and sibling routing are all present; nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by stating the exact data-URL form (data:image/png;base64,…), the decoded size ceiling, and the user-visible effect of 'name' (stored as agent-<name>.png and shown in the owner's browser), which the schema only partially conveys.

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

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

States a concrete verb+resource ('Store a small image ... in this R3 account's image library and get back the URL') and explicitly frames its role in the workflow with r3_component_set. It is clearly distinguishable from r3_image_list (reading existing art) and r3_texture_create (server-rendered texture sets).

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

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

Explicitly names the negative case ('NOT a way to upload an image file you already have') with the reason (base64 byte cost, no disk access) and routes to alternatives: r3_image_list for existing artwork, r3_texture_create for tiling material sets. The use case (checkerboard, gradient, test grid, noise tile) is spelled out.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses that each row is typed "texture" vs "environment", that these are not interchangeable and where each belongs, and that the returned URL is directly consumable by R3ComponentTexture.url. That is real operational context an agent cannot get from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, and every paragraph carries distinct, non-redundant information (search behavior, asset typing, upload boundary). It is longer than strictly necessary and could be tightened, but no sentence is filler.

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

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

An output schema exists, so return-field documentation is not needed. What an agent needs beyond that — what the URL is for, how the rows differ in kind, the search-vs-paging choice, and the boundary with r3_image_create — is all present.

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

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

Schema coverage is 100%, so limit/cursor semantics are already covered and the baseline is 3. The description earns above baseline by clarifying that search is evaluated server-side against every image on the account rather than the currently held page — a behavioral nuance the schema's "on the server" phrasing does not fully explain.

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

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

States a specific verb and resource ("List the images this R3 account owns") plus the return payload's key field ("the URL to use for each one"). It also implicitly separates itself from siblings that create or delete assets, and explicitly names r3_image_create as the only upload path.

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

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

Gives explicit when-to-use guidance ("Search by name rather than paging"), explains why (server-side match across the whole account, not the current page), and names the alternative tool for the adjacent job (r3_image_create). It also states the one thing you cannot do here (upload an existing file) and why.

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

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

Annotations already cover mutation/open-world/idempotent/destructive traits, and the description adds useful non-obvious behavior: 7-day validity, not public, free to recreate, and preview-image refresh behavior depending on whether an R3 tab has the project open. It does not explain why destructiveHint=true applies, but it does not contradict that annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the key constraints (7 days, not public, free) are stated early. The final sentence about preview-image refresh is detailed but still adds useful nuance rather than padding.

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

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

With an output schema present and a single fully documented parameter, the description supplies enough context to call the tool correctly, including expiry and privacy behavior. A brief note clarifying the destructive annotation would make it fully complete.

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

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

Schema coverage is 100%, so the projectId parameter is already fully documented in the input schema. The description only repeats that it comes from r3_project_create and adds no extra syntax or format guidance.

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

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

States a specific verb and resource: create a shareable preview link for a saved R3 project so it can be opened in a browser. This clearly distinguishes it from siblings like r3_preview_remove and r3_publish_live.

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

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

Explains the practical use case ("how the user sees what you built") and implicitly distinguishes it from publishing by noting it does NOT make the project public. It stops short of explicitly naming alternatives such as r3_publish_live or r3_preview_remove.

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

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

Goes well beyond the annotations: discloses the blast radius ('every preview link to it stops working at once (teammates' too)'), the post-state distinction (live project stays live vs. preview-only project becomes unpublished), the no-open-link refusal, and the needed 'publish:preview' right. The 'Deletes nothing' line usefully scopes what destructiveHint=true actually means (link removal, not data loss). Minor deduction only because it's already very close to complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and side effect, and every sentence carries real information (scope, exceptions, refusal, auth). Slightly weakened by colon-heavy run-on sentences that stack multiple clauses, but nothing is wasted.

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

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

An output schema exists, so return values need no explanation, and the description covers everything else an agent needs: side effects on teammates, live-vs-preview post-state, the refusal case, the permission requirement, and the related sibling. Nothing material is missing for a one-parameter tool.

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

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

Schema description coverage is 100% with a single required projectId already documented as 'The project id (r3_project_list)'. The description adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Remove the preview link of an R3 project') and immediately distinguishes itself from siblings by noting it 'Deletes nothing: r3_preview_create makes a new link.' An agent can tell this apart from r3_preview_create and r3_project_delete without opening any schema.

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

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

Explicitly states when to use it ('Only when the user asked for it') and the one narrow exception (when the preview link 'blocks an r3_project_delete the user asked for'), including why no separate request is needed. This is exactly the when/when-not/alternative guidance the dimension asks for.

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

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

Goes well beyond the annotations by disclosing a state side effect the schema can't convey: without `since` the call MOVES the read mark, and the mark belongs to the agent key/app connection so two conversations share it. That is exactly the kind of hidden behavior an agent needs. It falls short of 5 only because it doesn't note the mild tension with readOnlyHint (the cursor is mutated) nor any rate/volume caveats beyond the limit cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose in the first clause and keeps the summary formation/last-call relationship early. The second paragraph is dense but each sentence carries real routing or semantics information; minor cost is that the parentheticals make it harder to scan than it needs to be.

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

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

Output schema exists so return values need no explanation, annotations carry the read-only profile, and the description still adds the mark lifecycle, the auth requirement ('Needs project:read'), and the exhaustion behavior. An agent has everything needed to call this correctly on the first try.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds genuine meaning: it explains what a `seq` is, that `0` means everything still in the log, and — crucially — the interaction between `since` and `advance` (whether the mark moves). That interaction is not derivable from the field descriptions alone.

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

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

Names a specific verb and resource — listing what OTHER people changed in a project — and immediately narrows scope with 'oldest first, grouped per author and per thing' plus a concrete enumeration of change types. The line 'Your own changes are never listed' crisply separates it from any self-activity tool among the siblings.

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

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

Explicitly positions the tool against a known alternative surface: 'Every answer about a project already ends with a short "Since your last call" line; this is its full list.' It then splits usage into the two calling modes (with vs. without `since`) and states the conditions selecting each.

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