rosh_update_program

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

With no annotations, the description carries the full burden. It discloses the partial update behavior and write scope requirement. However, it does not address what happens when the program_id is invalid or provide error handling details, leaving some behavioral aspects unspecified.

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 concise, front-loading the core purpose and prerequisites in the first two sentences, then listing parameters in a clear block format. Every sentence is necessary and no redundant 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?

The description covers purpose, usage, and parameters well. An output schema exists, so the missing description of return values is less critical. The only gap is the lack of mention that the tool returns the updated program, but given the output schema present, the description is sufficiently complete for typical 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 input schema has no descriptions (0% coverage), so the description must compensate. It lists all 5 parameters with clear explanations: program_id as numeric, and the optional fields (title, description, code, target) with their semantics. This fully adds meaning beyond the schema structure.

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 'Update an existing program', specifying both the action and resource. It distinguishes the tool as the update operation among siblings like rosh_get_program, rosh_delete_program, etc., making its purpose unambiguous.

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 prerequisites ('Requires API key with write scope') and clarifies that only provided fields are changed, which guides correct usage. However, it does not mention when not to use the tool or suggest alternatives from the sibling list, missing an opportunity to improve decision-making.

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