run_cell

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It discloses the default 10-second wait, how '--wait' overrides it, that control comments are fully consumed and do not enter history or cell-magic bodies, that waiting expiry does not interrupt a running cell, the 5,000-token output truncation threshold, the effect of '--full-output', image display behavior with detail metadata, and the execution numbering scheme. This is comprehensive transparency.

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 long but well-structured with clear sections (输入, 等待上限, 完整输出, 图像展示, 执行编号与后续操作). Every section adds essential information, and the main purpose is front-loaded in the first sentence. It could be slightly more concise, but the organization makes it easy to navigate.

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 tool with one parameter and no output schema, the description is exceptionally complete. It covers input format, control directives, wait behavior, output truncation and the full-output override, image display options, execution numbering, and explicitly mentions the sibling tools for subsequent operations. An agent has all the information needed to invoke run_cell correctly and understand its effects.

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 only describes 'freeform' as '原始 IPython cell 源码文本' (raw IPython cell source text). The description adds significant meaning by explaining the 'loommux:' control comment syntax, including '--wait' and '--full-output' options, their combinations, validation behavior, and how they affect the execution. This goes far beyond the schema's minimal description, giving the agent actionable details for constructing valid input.

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's action: '向持久 IPython kernel 提交一个原始 IPython cell' (submit a raw IPython cell to a persistent kernel). It distinguishes itself from sibling tools by positioning itself as the submission entry point, with siblings like wait, execution_status, read_output, and search_output described as subsequent operations for handling the execution.

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 clear context for using the tool, including when to use the '--full-output' option (when full reading of information like files or materials is needed to avoid repeated reading overhead) and how to combine options. It also implies that for checking status or reading output, one should use the sibling tools (wait, execution_status, read_output, search_output), but it doesn't explicitly state when not to use run_cell itself. The guidance is implicit but effective.

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