Cursor: list owner actions

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.