Studio Rename

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: title-only mutation, type-based routing, note content preserved via a get-then-update, and note-backed mind maps routing back through the note system. It omits auth/permission requirements, error behavior, and whether the operation is idempotent.

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 in the first sentence, then structured detail about routing. The routing paragraph is long but earns its place by telling the agent it can pass any item without knowing its backing; a small amount of internal-RPC detail (e.g., the specific artifact type enumeration) could be trimmed.

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 briefly summarizes the return (item_id/type/new_title/is_mind_map), and it fully covers the routing complexity an agent would otherwise have to infer. Missing only failure/permission semantics, which are minor for a title-only rename.

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 0%, so the description must compensate. It explains that 'notebook' accepts a name or ID and that 'item' is a name-or-id ref resolved over the merged notes+artifacts list, which is real meaning beyond the bare schema. Only 'new_title' is left to inference from 'title only'.

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 opens with a specific verb+resource+scope: 'Rename a Studio item (title only) — a text note OR an artifact.' That distinguishes it from the sibling notebook_rename and source_rename by naming the resource domain (Studio items: notes/artifacts) rather than notebooks or sources.

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 establishes clear context for use — a notebook name/ID plus an item ref resolved over the merged notes+artifacts list, mirroring studio_delete — and signals that callers need not know the item's backing. It does not explicitly say when to prefer this over notebook_rename or source_rename, so it stops short of full alternative routing.

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