update_cell_source

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

With no annotations, the description carries the burden of behavioral disclosure. It explains that source is wrapped in the correct API structure based on cell_type, and that changes are only pushed after calling run_and_wait. It also notes the auto-refresh behavior, adding useful context beyond a simple mutation statement. It does not mention permissions or side effects like overwriting existing source.

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 compact and front-loaded with the primary action. Each sentence delivers relevant information: the purpose, cell_type semantics, the necessary follow-up call, and the auto-refresh behavior. There is 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?

Given the tool's mutation nature and lack of annotations, the description covers the core workflow and clarifies the most ambiguous parameter. It omits error conditions and permission requirements, but since an output schema exists, return value details are not necessary. The guidance to call run_and_wait provides essential context for successful use.

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 adds explicit meaning to cell_type by listing accepted values (CODE | SQL | MARKDOWN) and its default, which is not present in the schema. However, it does not explain source, cell_id, or project_id beyond what their names imply. With schema description coverage at 0%, this partial compensation for one of four parameters is insufficient to fully cover the gap.

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 'Write new source code to a cell (Python, SQL, or Markdown)', which clearly identifies the action and target resource. It distinguishes itself from sibling tools like create_cell or get_cell_source by emphasizing the update aspect and specific cell types.

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 provides explicit follow-up guidance: 'After updating cells, call run_and_wait to push changes to the app view.' This clarifies the intended usage workflow, though it does not explicitly contrast with alternative tools or state when not to use it.

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