Update Container

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

The description adds context beyond annotations: 'owned Container' implies an ownership prerequisite, and 'under existing hierarchy and Inbox restrictions' hints at validation constraints not captured by annotations. It also discloses partial-update semantics (only provided fields changed). Annotations already indicate non-read-only, non-idempotent, non-destructive behavior, so the description complements them.

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 a single, front-loaded sentence that efficiently conveys the core action and key constraints. No extraneous words.

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?

The tool has 6 parameters and no output schema, and the description omits essential context for safe invocation: it does not explain what 'Inbox restrictions' entail, which fields are updatable via partial semantics, or how this relates to sibling update tools for projects/collections. While the schema lists names and types, the description fails to provide behavioral context needed for correct 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?

Schema description coverage is 0% and the description mentions no parameters. The six parameters, including the required container_id and the enum type, are documented only by their schema names and types, with no added meaning from the description. This leaves the agent without semantic guidance for parameters beyond raw schema.

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 a partial update action on an owned Container, with explicit mention of hierarchy and Inbox restrictions. This distinguishes it from create/archive/delete container and from update tools for other resources, though it could explicitly reference alternatives.

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 implies usage when updating an existing container, but it does not explicitly state when to use this over update_project/update_collection or list before updating. It provides context about ownership and restrictions but no explicit when/when-not guidance.

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