cursor_sdk

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

No annotations are provided, so the description carries full burden. It explicitly states 'read-only, no agent spawn', clearly disclosing its behavioral safety. It also mentions 'Fleet-curated', indicating curation by a specific team. For a guidance tool, this level of transparency is sufficient and adds trust.

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

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

The description is extremely concise: two sentences. The first sentence immediately states the tool's nature and key attributes (read-only, no agent spawn). The second sentence adds fresh context about the SDK release and usage. No redundant or vague text.

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's simplicity (one parameter, no annotations), the description covers all essential aspects: what it does, its safety, when to use it, and what content it provides. It also relates to sibling tools via 'complements cursor_docs topics'. The presence of an output schema (though not shown) further reduces the need to describe return values.

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 parameter 'operation' is fully described in the schema with enum values and descriptions. The tool description adds extra context by listing specific topics like 'custom tools, auto-review, JSONL stores, nested subagents', which gives meaning to what guidance is available beyond the enum names.

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 it provides 'Fleet-curated @cursor/sdk / cursor-sdk guidance', establishes itself as a read-only SDK reference, and distinguishes from sibling 'cursor_docs' by saying it complements rather than duplicates. Specific SDK release features are listed, giving concrete 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 explicitly advises 'Use before writing new headless automation' and notes that it 'complements cursor_docs topics', giving a clear use case and hinting at when to prefer cursor_docs instead. It does not explicitly list all alternatives but the context indicates this is the SDK-specific guidance tool.

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