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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the agent knows the operation is safe. The description adds two useful behaviors: it 'Launches nothing' (no trigger of builds or jobs) and it operates 'from readback you hold' (no remote fetching). No contradiction with annotations.

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

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

Two sentences totaling 24 words, with the core purpose front-loaded and side effects/return stated immediately after. There is no redundancy or filler; every sentence 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?

The complex 8-parameter schema is covered in detail by property descriptions, and an output schema exists, so the description needn't repeat return values. It does omit an explicit list of prerequisite readback tools (e.g., cursor_list_builds), though the schema property descriptions mention them. Overall it is adequate given the supporting structured data.

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 88%, so the schema already documents the parameters, including the roles of builds, baseline, observed, and toolchain. The description only groups them into three assessment categories (Build health, source drift, toolchain drift), which adds a bit of conceptual organization but no new per-parameter detail. Baseline of 3 is appropriate given high schema coverage.

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

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

The description uses a specific verb ('Judge') and names the exact resources: Build health, source drift, and toolchain drift. It also states the mode ('from readback you hold') and the outcome ('returns a scheduler exit code'), which distinguishes it from sibling tools that inspect definitions or list environments. An agent can tell it apart from cursor_validate_environment_definition or cursor_inspect_environment_definition without opening those tools.

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

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

The phrase 'from readback you hold' implicitly tells the agent that this tool consumes previously gathered data rather than fetching it, and 'Launches nothing' signals it is a pure assessment rather than an action. However, it never explicitly states when to prefer this tool over alternatives like cursor_inspect_environment_definition, nor any exclusions. The usage context is inferable, not 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 declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context by disclosing that scripts and MCP patterns are compared by digest and that no field value can leave through the diff, which is a significant security/privacy guarantee beyond what annotations 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?

Two tight sentences, front-loaded with the core purpose and immediately followed by the key behavioral guarantee. Every clause adds information without redundancy.

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

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

With a full input schema, output schema, and annotations, the description covers the essential behavior and the privacy-critical digest mechanism. The only gap is that 'bounded' is not fully elaborated, but the output schema and 100% parameter documentation make the overall context 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%, with each property (base, proposed, text, source, repoRoot) already extensively documented. The description does not add parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a precise operation: a bounded semantic diff between two Cursor environment definitions. This clearly distinguishes it from sibling validation, inspection, and listing tools, and the verb-resource structure ('diff environment definitions') leaves no 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?

The description implies this tool is used when comparing two environment definitions, but it does not explicitly state when to use or avoid it relative to alternatives like cursor_validate_environment_definition or cursor_inspect_environment_definition. The 'bounded' and digest-based wording suggests a safe comparison use case, but no exclusions or alternative routing are given.

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, and non-destructive behavior. The description adds useful context about what the inspection surfaces (repos, settings, web URL, recent run id) but discloses no additional behavioral traits such as error conditions, side effects, or prerequisites. It is consistent with annotations.

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

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

The description is a single, front-loaded sentence that states the verb, resource, and return fields without fluff. Every part earns its place, and there is no redundant or repetitive wording.

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 one parameter, a rich input schema description, full annotation coverage, and an output schema, this description is sufficient. An agent can correctly understand what the tool does, what input is required, what to expect in the return, and that it is safe to call.

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 input schema provides 100% documentation for the only parameter, agentId, including format ('bc-<uuid>') and constraints. The description adds no extra parameter meaning, so the baseline of 3 is appropriate since schema carries the full burden.

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

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

The description uses a specific verb ('Inspect'), a singular resource ('one agent'), and lists exactly what is returned: repos, settings, web URL, and most recent run id. This clearly differentiates it from sibling tools like cursor_list_agents, which enumerate multiple agents.

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

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

The description implies usage context: call this when you need detailed information about a specific agent, identified by agentId, rather than listing agents. It does not explicitly name cursor_list_agents or state when not to use it, but the singular phrasing provides clear contextual 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 the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: the generated URL expires in 15 minutes, and it applies to exactly one artifact path. This goes beyond annotation scope and gives the agent timing and scope knowledge.

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

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

A single sentence that front-loads the core action (minting a 15-minute presigned URL) and immediately ties it to the source tool. Every word earns its place; there is zero filler or redundancy.

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

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

The tool is simple with two well-documented parameters, an output schema is present (so return format is covered), and the description covers the essential behavioral aspect (time-limited URL). No critical operational guidance is missing for an agent to correctly invoke this 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%, so both parameters are fully documented. The description adds semantic value by referencing 'as cursor_list_artifacts returned it,' clarifying that the path must match the exact output of the listing tool, which is not stated in the schema. This is a meaningful addition beyond the schema.

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

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

The description states a specific verb ('Mint'), a precise resource (a 15-minute presigned download URL), and scopes it to a single artifact path sourced from cursor_list_artifacts. This clearly differentiates it from sibling tools like cursor_get_agent or cursor_list_artifacts, and avoids any tautology.

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 phrase 'from cursor_list_artifacts' explicitly indicates the prerequisite step: the agent must first call cursor_list_artifacts to obtain a valid path. While it doesn't spell out when not to use this tool or name alternatives, the context is clear that this is the download step after listing. It conveys usage context well, though lacks explicit exclusionary 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, openWorld, idempotent, and non-destructive flags. The description adds meaningful context beyond annotations by noting the dependency on a configured Cursor CLI and specifying the data fields read (candidates, source, precedence, digest). The cryptic 'Scripts stay digests' is the only weak point.

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 short and front-loaded, but the second sentence 'Scripts stay digests' is unclear and does not earn its place. It adds confusion rather than value, making the overall structure only partially effective.

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 explained. The description covers the operation's scope and prerequisite (configured CLI), and annotations handle safety. The cryptic final phrase is the only gap; otherwise the definition is sufficiently complete for an agent 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% and the parameter description is already detailed, clarifying how to obtain environmentPublicId from cursor_list_environments. The tool description does not add additional parameter semantics beyond what the schema provides, so a baseline score of 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?

The description clearly states the action ('Read') and resource ('one environment's configuration candidates, source, precedence, and digest'), distinguishing it from list-type siblings. The phrase 'through a configured Cursor CLI' adds a prerequisite context. However, 'Scripts stay digests' is cryptic and slightly detracts from clarity.

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

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

The description implies use for a single environment's config, contrasting with list_environments, but does not explicitly state when to use this tool over alternatives or when not to use it. There is no mention of exclusions or alternative tools, leaving routing partially 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that the tool returns final reply 'once it has finished', implying it may not return that field for running runs, which is useful. However, it does not disclose behavior like potential delay or error on non-existent run, which is minor given 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?

Single sentence, concise, and front-loaded with the key information: what it inspects and when the reply is available. No wasted words; every element adds value.

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

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

The tool is a simple read operation (2 params, annotations cover safety, output schema exists). The description covers the core output aspects (status, duration, branch/PR, final reply) and timing. Given the existence of an output schema and annotations, the description is sufficiently complete; no major gaps 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 description coverage is 100%, so both parameters (agentId and runId) are fully documented in the schema. The description does not add new meaning beyond what the schema provides, but it does aggregate that the runId identifies the run and agentId identifies the parent agent. Baseline 3 is appropriate when schema covers parameters fully.

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

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

The description clearly states the tool inspects a single run and lists the specific attributes inspected (status, duration, reported branch or PR, final reply). It distinguishes from sibling tools like cursor_list_runs (which lists runs) and cursor_inspect_runs (which likely inspects multiple runs), though it does not explicitly name them. The verb 'Inspect' and resource 'one run' provide clear purpose.

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

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

The description implies that this tool is for inspecting a single run, contrasting with list/inspect siblings, but does not explicitly state when to use it vs. alternatives like cursor_list_runs or cursor_wait_run. It does not mention prerequisites (e.g., run must exist) or when not to use (e.g., for live runs, use cursor_wait_run).

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. It adds meaningful behavior beyond annotations: that usage is aggregated and broken down per run, and that runId scopes the report. This complements rather than repeats the structured 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?

Two sentences and under 20 words, with the core purpose front-loaded ('Report an agent's token usage'). It also front-loads the main action before the optional scoping detail. No filler or redundancy.

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

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

Output schema exists, so the response format is covered; annotations cover safety. The description covers what it does (usage report), how it organizes results (totalled/per-run), and how to narrow scope (runId). For a simple query with two parameters, this is 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 baseline is 3. The description adds semantic meaning by explaining that runId scopes the report to one run and that the tool reports 'an agent's' usage, tying agentId to the purpose. This goes beyond the schema's format-only descriptions ('run-<uuid>' and 'bc-<uuid>').

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 'Report an agent's token usage, totalled and broken down per run' – a specific verb and resource, and immediately distinguishes itself from siblings like cursor_get_run or cursor_list_runs by being about usage aggregation. It also specifies the optional runId scoping with 'Pass runId to scope it to one run', reinforcing its precise purpose.

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 is clear about how to use the tool (pass runId to scope to a single run) but does not explicitly say when to use it vs alternatives. There are many siblings that inspect runs or agents, and this description doesn't mention any alternatives or exclusion criteria, so agents must infer when this usage report is the right choice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is clear. The description adds the key behavioral nuance: supported controls fetch live data; others return a 'capability result' (a stubbed or metadata response). This is valuable beyond 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?

One concise sentence that front-loads the action and resource, then adds the critical behavior in a second clause. No fluff, every word 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?

For a single-parameter read tool with rich annotations and an output schema, the description is almost complete. Missing aspects: which controls are 'supported' vs. not is not enumerated (but the enum gives the list). It's adequate for the task; slight gap on specifying what 'capability result' means in practice.

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 parameter 'control' is well-documented in the schema with an enum. The description adds a high-level note about live vs. capability but doesn't explain each enum value or their semantics. Baseline 3 is appropriate since schema does most of the 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?

Description states a clear verb ('Read') and resource ('workspace or account control'). It distinguishes supported controls (fetch live) from unsupported (capability result). However, it doesn't explicitly differentiate from sibling tools like cursor_list_workspace_controls or cursor_whoami, which are more specialized; this is mostly clear but slightly generic.

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

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

The description implies when to use it: for reading a single control, with qualification about supported vs. capability results. It doesn't mention when NOT to use it (e.g., for listing all controls use cursor_list_workspace_controls). No explicit alternatives are named, but context suggests this is a generic read with a control enum that guides 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context beyond that: it states that the tool returns a 'Normalized view' and explicitly notes 'Scripts are digests.' This informs the agent that the output is transformed (not raw) and that scripts are represented as hashes, which is useful for interpreting results. This goes beyond the structured annotations.

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

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

The description is a single, tightly written sentence. It front-loads the core purpose ('Normalized view of a Cursor environment definition') and then enumerates the included components without any filler. Every clause adds informational value, and the 'Scripts are digests' note is a meaningful qualifier. No redundancy or wordiness.

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 tool has an output schema (so the return structure is defined externally), the description covers what the inspection yields: a normalized view of install/start, terminals, ports, MCP policy, build paths, and snapshot input, plus the digest representation of scripts. It does not mention return format or error cases, but those are likely handled by the output schema and the tool's runtime. The description is adequate for an inspect operation.

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

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

Schema description coverage is 100%, and every property in the 'definition' object has a description explaining its semantics (e.g., text is JSONC, source has an enum with 'delegated-saved' labeled as untrusted evidence, repoRoot must be '.'). The tool description adds no additional parameter-level guidance – it only lists what the definition contains. Baseline 3 is appropriate since the schema alone is fully self-explanatory.

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 specifies a clear verb ('inspect') and resource ('environment definition'), and adds that it provides a 'Normalized view' with a concrete list of contents (install/start, terminals, ports, MCP policy, build paths, snapshot input). It does not explicitly contrast with sibling tools like validate or diff, but the term 'inspect' and 'Normalized view' imply a read-only, processed reading, which differentiates it enough for most agents.

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

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

There is no guidance on when to use this tool versus alternatives. Sibling tools such as cursor_validate_environment_definition, cursor_diff_environment_definition, and cursor_get_environment_configuration exist, but the description never mentions them or states conditions that would make one preferable. The agent is left to infer from the name and the generic verb 'inspect' that it is for reading a definition, which is not explicit enough for confident 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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine non-obvious behavior beyond that: the 45-second execution bound, strict exact-match semantics, and the resume mechanism via remaining.fromIndex. The per-item partial-failure guarantee ('one undecidable agent does not refuse the whole call') lives in the schema rather than the description, so some behavioral context is allocated to the schema. No contradiction with annotations.

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

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

Two dense sentences, front-loaded with purpose and zero filler — every word earns its place. However, phrasing like 'under one 45s bound' and 'remaining.fromIndex' is cryptic shorthand that references mechanisms the description doesn't unpack, so brevity slightly trades away clarity. Still efficient overall.

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 both parameters are fully documented in the schema, so the description doesn't need to explain return values or parameter formats. The description covers the key behavioral facts (batch scope, time bound, resume, exact-match). The cryptic tone and the lack of explicit guidance around the 45s bound (retry vs. treat as failure) leave small gaps, but for a batch tool with rich structured metadata it is largely 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 description coverage is 100%, with rich descriptions for both parameters (runs: order, repeat handling, per-item result statuses; fromIndex: resume semantics). Under the coverage rule the baseline is 3. The description adds only marginal value here — the 'continue at remaining.fromIndex' phrasing lightly ties the two params together but does not exceed 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?

'Read status for up to 64 agent/run id pairs' states a specific verb (read), resource (run status), and scope (up to 64 specific pairs in caller order). This clearly distinguishes it from siblings: cursor_get_run (single run), cursor_list_runs (list all runs), cursor_wait_run (wait on runs). An agent can tell when this batch-inspection tool applies 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?

The description gives operational constraints — 'Exact pairs only', 'under one 45s bound', 'continue at remaining.fromIndex unless complete' — which implicitly tell an agent how to use it (strict matching, resumable pagination). But it never explicitly states when to prefer this over cursor_get_run or cursor_wait_run, nor any exclusions. Usage context is implied, not 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 establish readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context beyond those hints by specifying what is inspected and explicitly excluding repository listing, all without contradicting the annotations.

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

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

Two short sentences, front-loaded with the main scope and closed with a useful negative. Every clause earns its place; there is no repetition of the title or annotations.

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 parameterless, safe, inspection tool with an output schema and rich annotations, the description is nearly sufficient. The only completeness gap is selection guidance: it does not explain how this differs from the similarly-named cursor_whoami and cursor_list_workspace_controls tools.

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

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

The tool has zero parameters and 100% schema coverage, so the schema leaves no ambiguity. Per the baseline for zero-parameter tools, the description need not add parameter detail; the absence of explanation is acceptable.

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

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

The description uses a specific verb ('Inspect') and names concrete resources: API-key identity, entitlement, and the workspace-control surface. It also states a negative scope ('Does not list repositories'), which separates it from cursor_list_repos, but it does not differentiate itself from the overlapping cursor_whoami and cursor_list_workspace_controls 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?

No explicit when-to-use guidance or named alternatives are provided. 'Does not list repositories' gives one exclusion, but in a sibling group with cursor_whoami and cursor_list_workspace_controls, the agent is left to infer which inspection surface this tool covers versus its peers.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context about ordering ('newest first') and warns that 'Status is not execution state,' which prevents misinterpretation. It does not mention pagination behavior, but annotations cover safety and idempotency.

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 two sentences with zero fluff. The main purpose is front-loaded ('List cloud agents, newest first'), and the caveat is a single additional sentence. This is an exemplary concise structure.

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

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

The tool has an output schema and annotations that cover safety and idempotency, which reduces the burden. However, the description omits pagination mechanics (limit, cursor) and filtering options (prUrl, includeArchived) beyond what the schema partially provides. Since limit and cursor are undocumented in both schema and description, an agent may not know how to page through results. This is a notable gap for a list endpoint.

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 50%: prUrl and includeArchived have descriptions, but limit and cursor are undocumented in the schema. The description itself adds no parameter information at all, so it fails to compensate for the missing schema coverage. For a tool with four parameters, this leaves half of them ambiguous.

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

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

The description clearly states the tool lists cloud agents and specifies ordering ('newest first'). It also adds a clarifying caveat about status not being execution state, which helps differentiate from cursor_get_run. However, it does not explicitly distinguish itself from sibling tools like cursor_get_agent (which retrieves a single agent), so it's not a perfect 5.

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 explicitly tells the agent to use cursor_get_run when execution state is needed, providing a clear when-not condition and pointing to an alternative. It does not discuss other usage contexts or alternatives like cursor_get_agent, but the key exclusion is 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 cover read-only, idempotent, non-destructive behavior. The description adds useful semantic context beyond those annotations: the artifact directory contains only saved files, and code changes should be looked for on the branch, not in this listing. This helps shape agent expectations without contradicting the annotations.

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

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

Two short sentences with no filler. The first sentence states the core action and resource, and the second adds a valuable scoping clarification. Every sentence 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?

The tool is simple: one required, fully documented parameter; strong annotations; an output schema; and a description that clearly defines what is and is not included. There are no meaningful gaps that would prevent an agent from selecting and invoking the tool 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% and the only parameter, agentId, is already well documented with format guidance ('bc-<uuid> form'). The description adds no parameter-specific information, but the schema fully carries that burden, so a baseline score of 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?

The description states a specific verb and resource: 'List files an agent saved to its workspace artifacts directory.' It also draws a clear boundary from code changes by noting they land on the branch, which distinguishes this tool's purpose despite many sibling cursor_* tools.

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

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

The description gives clear context for when the tool is appropriate: inspecting workspace artifact files. The statement 'Code changes land on the branch, not here' is an effective when-not signal, telling the agent not to expect code changes in this listing, though it does not name a specific alternative tool.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds the useful failure behavior 'Without one, reports why the authority is unavailable,' but the term 'authority' is somewhat vague and little else is disclosed beyond 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?

Two short sentences deliver the core action and the key failure case with no wasted words. The primary operation is front-loaded, making the description easy to scan.

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 a single optional parameter, full schema coverage, an output schema, and safety-relevant annotations, the description covers the prerequisite and fallback behavior. The only minor gap is the ambiguous phrase 'authority,' which could be clearer, but nothing essential for invoking the 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 schema covers the only parameter fully with a description and enum values, so the description does not need to add parameter detail. The tool description provides no additional insight into the `scope` parameter, earning the baseline score for high schema coverage.

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

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

The description clearly names the operation ('List saved cloud environments') and the required mechanism ('configured Cursor CLI'). It does not explicitly contrast itself with sibling list tools, relying on the resource name for differentiation, so it stops short of a 5.

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

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

It communicates the prerequisite of a configured Cursor CLI and explains what happens when that prerequisite is missing. It does not mention alternatives or exclusions, but for a simple list operation with distinct sibling tool names, the usage context is reasonably clear.

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, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the behavioral detail that omitting the model selects the account default, which is useful beyond annotations. It does not disclose other behaviors like list ordering or deprecation status, but given the annotations' coverage, this is adequate.

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 short sentences with zero waste. The purpose is front-loaded, and the usage note follows immediately. Every word 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?

The tool is simple with no parameters and an output schema present. The description explains what it does and the default behavior. The output schema handles return format, so nothing needed by an agent 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?

The tool has zero parameters, and the schema coverage is 100% (trivially). Per the rules, 0 params merits a baseline of 4. The description adds no parameter details because there are none to explain, which 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?

The description clearly states the verb 'list' and the resource 'model ids' with the context of launching a cloud agent. It distinguishes itself from sibling tools by focusing on models, not repos, agents, or runs. The added note about omitting the model for the default further clarifies its purpose.

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

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

The description implies usage: it lists valid model ids for launching a cloud agent, and the note about omitting the model for the default gives practical guidance. However, it does not explicitly contrast with alternatives or state when not to use it. The context is clear enough, but explicit exclusions would make it 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe/read-only nature is already covered. The description adds valuable context: 'launches nothing' clarifies it's non-executing, and 'Returns the exact owner action for the ids you pass' indicates behavior. It also hints that 'no supported authority performs' these actions, implying this is a planning/query tool. However, it doesn't disclose how the action is returned (e.g., does it simulate the action or just describe it?), nor does it mention any authentication requirements or potential side effects despite read-only semantics. Still, with annotations strong, the description adds moderate value beyond them.

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

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

The description is two sentences with no fluff, front-loading the core purpose ('Catalog of Build and environment operations') and then clarifying scope ('Returns the exact owner action... launches nothing'). It's concise and efficient, though the phrase 'no supported authority performs' is somewhat awkward and could be sharper, but it doesn't waste words. Structure is good for quick scanning.

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 tool has no required parameters (all optional) and an output schema exists, the description doesn't need to explain return structure. However, the tool has 5 optional parameters with complex relationships (e.g., action-specific requirements) and a non-trivial context (owner actions vs. standard authority actions). The description doesn't clarify how to choose the action enum values or which parameters are needed per action, and it doesn't explain what 'owner' means or how this list is populated (e.g., is it a catalog of possible actions or a list of pending owner actions?). This is a moderately complex tool, and the description leaves gaps in usage semantics, so a 3 is fair.

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

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

Schema description coverage is 100% and each parameter has a detailed description in the schema. The tool description does not add any additional meaning beyond the schema; e.g., it doesn't explain the interplay between parameters like 'action' and 'environmentPublicId' beyond what schema says. The description names action types but doesn't clarify which parameters are needed for which actions (e.g., that 'supersededBuildId' is only for ROLLBACK_BUILD). Since the schema already does the heavy lifting, baseline 3 is appropriate; the description doesn't compensate for any gaps but also doesn't need to.

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 clear purpose: listing owner actions for build and environment operations. It enumerates specific action types (cancel, activate, deactivate, rollback, restore, host-wide trigger), distinguishing it from generic list tools among siblings. However, it doesn't explicitly name a sibling alternative, and the phrase 'no supported authority performs' is vague—while it suggests this is for owner-level operations, it doesn't clarify what 'owner' means in the context, so the differentiation is partly implied but not explicit.

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

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

The description gives context: it returns exact owner actions for given IDs and launches nothing, implying it's for querying what-actions-would-be-taken rather than executing them. It does not explicitly state when to use this tool versus siblings like cursor_list_runs or cursor_inspect_runs, nor does it provide exclusions or alternatives. The 'no supported authority performs' hint suggests certain actions are not available to regular authorities, but the usage boundary is not clearly articulated—the agent might not know when to pick this over other list tools.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false. The description adds a meaningful behavioral constraint beyond those annotations: 'Rate limited to one call per minute.' This is important operational context that helps the agent avoid throttling. No contradiction exists.

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

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

The description is two short sentences with no filler. The primary purpose is front-loaded, and the rate limit is a single additional sentence that earns its place. Every word contributes useful information.

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

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

For a simple zero-parameter read-only tool with an output schema and strong annotations, the description is complete. It covers what the tool lists, the scope of those repositories, and the one operational constraint (rate limit). Nothing essential is missing for an agent 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?

The tool has zero parameters, and schema description coverage is trivially 100%. According to the rubric, zero-parameter tools should receive a baseline of 4 because there are no parameter semantics to explain. The description still adds semantic context about what the returned repositories represent, which is sufficient.

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: 'List GitHub repositories'. It further scopes the tool to repositories Cursor can launch an agent against, which distinguishes it from the other cursor_* tools that focus on agents, runs, environments, or models. The purpose is immediately clear even without inspecting 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?

The description implies usage context by defining the resource ('repositories Cursor can launch an agent against'), which tells the agent what this tool is for. However, it does not explicitly state when to prefer this tool over alternatives or mention any exclusions. The guidance 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?

Annotations already provide readOnlyHint and idempotentHint, so the description does not need to repeat safety. The description adds value by noting 'newest first' ordering and explaining that status carries CREATING/RUNNING/terminal values, which informs the caller on interpreting the output. No contradiction with annotation; the operation is read-only.

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 two sentences, front-loading the action and then adding a useful note about status values. Every word earns its place, and the length is appropriate for a simple listing 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?

There is an output schema, so return values are covered. The description adequately states scope and ordering, but it does not mention that the result is paginated via limit/cursor, and the usage guidance gap (dimension 2) also contributes to a slight incompleteness. The information provided is useful but not fully complete for a tool with these three parameters.

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 only 33% (only agentId has a schema description). The description relates the agentId to 'an agent's runs' but says nothing about limit (page size) or cursor (pagination token). It does not compensate for the low schema coverage and leaves the two optional parameters undocumented.

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

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

The description clearly states the action ('List'), the resource ('runs'), and the scope ('an agent's runs') plus the ordering ('newest first'). It distinguishes from sibling tools like cursor_get_run (single run) and cursor_inspect_runs (different purpose) by resource level, though it doesn't explicitly name any sibling.

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?

No guidance is provided on when to use this tool versus alternatives. It does not mention when a list is preferred over cursor_get_run, cursor_inspect_runs, or cursor_wait_run, nor any exclusions or conditions.

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 non-destructive behavior, so the safety profile is covered. The description adds the scope and status categories, but does not disclose behaviors like pagination, result limits, or authorization requirements; with annotations present, this is adequate.

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

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

A single, front-loaded sentence conveys the full purpose with no filler. Every element is relevant.

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

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

For a simple read-only listing tool with an output schema and complete parameter documentation, the description is sufficient. Optional filters are covered by the schema, and the description conveys the core purpose and result categories.

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 have useful enum descriptions, so the description does not need to compensate. It adds no meaningful parameter details beyond the schema, and it uses 'unavailable' where the schema specifies 'unavailable-on-plan', a minor inconsistency.

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 clear verb ('List') and a specific resource ('Cloud Agent workspace and account controls'), and it explicitly enumerates the status categories returned. This distinguishes it from sibling tools such as cursor_get_workspace_control, which targets a single control.

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

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

The description implies the tool is for getting an overview of controls and their support status, and the optional filters suggest narrowing by read/write or status. However, it does not explicitly state when to prefer this tool over alternatives such as cursor_get_workspace_control or cursor_inspect_workspace.

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/idempotent/non-destructive annotations, the description discloses the bounded read behavior, the resume-vs-replay semantics of lastEventId, and the fact that status is intentionally not included and the run is not canceled. These are meaningful behavioral traits not encoded in the structured fields.

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 compact sentences: the main action is front-loaded, then continuation behavior, then the important non-behaviors. There is no filler, repetition of annotations, or redundant parameter detail.

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 tail-style tool with an output schema and strong annotations, the description covers the essential contract: what is read, how to resume, and what it does not do. The only minor gap is not explicitly tying durationMs to the 'bounded' wording, but the schema default and range make the connection recoverable.

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 description explains the most subtle parameter, lastEventId, by saying it resumes the stream and that omitting it causes a replay from the beginning. The 'bounded' qualifier makes durationMs inferable alongside its schema default, and agentId/runId are self-evident identifiers, which partially compensates for the 0% schema description coverage.

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 sentence states a specific verb (Read), resource (run activity), and scope (bounded excerpt), so the purpose is immediately clear. It distinguishes itself from get/list/wait siblings by noting status is checked separately and that it does not cancel the run, though it does not name the sibling explicitly.

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 direct usage guidance: pass lastEventId back to resume, otherwise Cursor replays from the beginning. It also sets clear exclusions by saying status is checked separately and the tool does not cancel the run, though it stops short of naming the alternative tools.

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 destructiveHint false, covering the safety profile. The description adds value by disclosing that results are reported in separate categories. It does not mention the optional syncTarget behavior, but the schema documents that and annotations indicate no destructive side effects.

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

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

A single, tight sentence states the action and the key output categories with no filler. The most important information is front-loaded and every word 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?

Given the rich input schema, output schema, and safety annotations, the description covers the essential behavioral context. The only minor gap is not surfacing the optional syncTarget capability, but that is already documented in the schema and is not required for basic validation usage.

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

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

Schema description coverage is 100%, and the schema already provides detailed descriptions for definition, source, repoRoot, and syncTarget. The description itself adds no parameter-level meaning, so the baseline score of 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?

The description clearly states the tool checks a Cursor environment definition against the published schema and explicitly lists the three reporting categories (schema errors, safety warnings, capability limitations). This is specific enough to distinguish it from sibling tools like inspect_environment_definition or diff_environment_definition.

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 context is implied: use this tool when you need to validate a definition against the schema. However, the description provides no explicit when-to-use guidance, exclusions, or references to alternative sibling tools.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it polls, enforces a wait bound, and returns a timedOut flag. It also discloses that it can be called repeatedly to continue waiting. No contradiction is present.

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 two sentences, front-loaded with the core purpose and termination condition. Every word adds value: it states the action, the timeout default/max, the return behavior, and the re-call guidance. No filler or repetition.

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

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

The tool has an output schema (not shown) so return values are already documented. The description focuses on the polling semantics, which is the tool's unique aspect. It covers the primary use case, timeout handling, and re-polling. Minor gaps like error behavior for non-existent runs are not covered but are likely handled by the runId validation and output schema. Overall, it is 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 coverage is 100%, so each parameter is already described. The tool description adds the default for waitMs (30s) and clarifies that waitMs is an upper bound on the wait. It also explains how waitMs relates to polling behavior. This supplements the schema meaningfully without redundancy.

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

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

The description clearly states a specific action ('Poll one run') and a specific resource, with a precise termination condition ('until it is terminal or waitMs elapses'). It also explicitly differentiates from the sibling cursor_get_run by noting it returns the same data plus a timedOut field, making the distinction obvious.

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

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

The description gives clear context: it is used to wait for a run to reach a terminal state, and tells the agent to call again to keep waiting if the timeout expires. It does not explicitly say when NOT to use it or name the alternative cursor_get_run, but the mention of returning its result plus timedOut implies that get_run is the non-polling alternative. This is sufficient for an agent to choose correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds value by specifying the exact return content (name, creation date, email), which is not in the annotations. It accurately reflects a non-destructive, side-effect-free operation.

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

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

A single, efficient sentence that front-loads the purpose and output. There is no redundancy or filler, and every word contributes to understanding the tool's function.

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 parameterless, read-only tool with an output schema, the description fully covers what the agent needs to know to invoke it correctly. The output schema documents the return format, so the description need not elaborate further.

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

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

The tool has zero parameters and the schema is completely covered (100% coverage trivially), so the baseline is 3. The description adds no parameter-specific details, but none are needed since there are no parameters to document.

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 ('Verify'), a clear resource ('the Cursor API key'), and the exact output fields (name, creation date, owning email). It is unambiguous and distinct from all sibling tools, which handle different resources like models, repos, or runs.

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

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

The description clearly implies when to use this tool: whenever you need to confirm API key identity or retrieve its metadata. No explicit alternatives or exclusions are given, but given its unique role among siblings, the context is sufficient for an agent to select it.

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