push_common_ui_widget

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

Annotations only declare the generic write/not-idempotent/not-destructive profile; the description adds the decisive behavioral fact that this is RUNTIME ONLY and depends on a live PIE session, because the container's list and pool are Transient. It also discloses that the stack itself performs activation and that the returned counts are read post-push ('evidence rather than an echo') rather than echoes.

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 core operation is front-loaded in the first clause, with the WARNING and returns block cleanly segmented. It is longer than strictly necessary and leans on capitalization for emphasis, but every sentence (runtime constraint, follow-up readers, return field meanings) carries information.

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?

There is no output schema, yet the description still enumerates the five returned fields and explains that widget_count and active_widget are read off the stack after the push. Combined with the runtime prerequisite and the pointer to reader/focus tools, an agent has everything needed to call and interpret this correctly.

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%, so stack_widget_name, widget_class, world and player_index are already fully documented in the schema, making 3 the baseline. The description adds only marginal semantics ('resolved like click_pie_widget, nested Widget Blueprints included') and does not describe the world/player_index selection behavior.

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 gives a precise verb and resource ('Push a screen onto a LIVE CommonUI activatable stack in the running PIE session') and explicitly positions itself against the sibling that creates the stack ('create_common_ui_stack only puts the stack in place; its contents are populated at runtime'). An agent can distinguish this from both the create and pop paths without opening a schema.

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 states the motivating scenario concretely ('open the pause menu, then the options page, now check the back button' is reproducible) and names the tools to use for the follow-up steps (get_common_ui_stack / read_pie_widgets, set_pie_widget_focus). What is missing is an explicit when-not / inverse pointer to pop_common_ui_widget, leaving the inverse relationship to inference.

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