cook_top_node

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

With no annotations, the description carries the full burden, and it does disclose that block controls whether the call waits for completion and generate_only skips actual cooking. That is genuine behavioral context beyond the bare schema. It still omits failure behavior, duration expectations, and side effects on existing work items, which matters for an execution tool.

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 lead sentence is front-loaded and the parameter list is compact with no filler prose. The 'ctx: MCP context' line is wasted space for an agent caller, keeping it from a 5.

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 three-parameter execution tool with no annotations and no output schema, the description covers the mechanics but says nothing about return values, error handling, or what a completed cook yields. The block flag implies a completion signal, but the agent is left to infer the rest.

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 0%, so the description must compensate, and it does name each parameter with meaning: wait-for-completion for block and generate-without-cooking for generate_only. It does not give format or path syntax for node_path, and 'ctx: MCP context' is not a real caller-facing parameter, so the compensation is only partial.

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?

States a specific verb (cook) and resource (TOP node) and clarifies the effect: executing the node's work items. It is clearly distinguishable from read-only PDG siblings like get_pdg_graph or get_work_item_states. However, it does not explicitly differentiate itself from the other cook-related siblings such as cook_frame_range or generate_static_items.

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?

There is no when-to-use or when-not-to-use guidance. Nothing routes the agent between this and cook_frame_range, generate_static_items, or the cancel/pause siblings, nor does it state prerequisites (e.g., that a TOP network must exist or be schedulable).

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