baron_issue_read

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

For the operations it does describe, it is transparent: get yields 'one normalized issue,' query yields 'a filtered list,' and iterations returns sprints with a current flag and explicit empty-when-none behavior. However, with no annotations, the description carries the full behavioral burden but says nothing about classify or trace, which are valid enum values, nor about side effects, permissions, ordering, or pagination.

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 front-loaded with a clear purpose and uses code spans and arrows to make the op breakdown easy to scan. Every clause contributes operational information, and nothing is wasted.

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 is complex with 5 ops, 7 parameters, and no output schema, but the description documents only 3 of the 5 ops and gives no return field details or accepted values for role/typeRole. The missing classify and trace operations and undefined query filter semantics leave significant gaps for an agent trying to invoke the tool 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 only 14%, but the description compensates by mapping each parameter to an operation: id to get, role/typeRole/assignee/iteration/limit to query, and no args to iterations. It adds useful semantics for sentinel values `@me` and `@current` and clarifies that iterations takes no additional arguments. It does not define the distinction between role and typeRole or the exact values they accept.

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?

Description opens with 'Read work items,' naming the verb and resource, then enumerates get/query/iterations with their outputs, making the tool's core purpose unambiguous. It is distinguishable from siblings like baron_issue_write and baron_issue_move by the explicit 'Read' framing. However, the schema enum includes classify and trace, which the description silently omits, so it is not fully complete.

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 op-by-op breakdown gives clear within-tool selection criteria: use get for a single id, query for filtered lists, and iterations for sprints. It does not explicitly mention when to prefer this tool over sibling alternatives such as baron_scm_read or baron_issue_write, nor does it state that mutations should go elsewhere; that is left to inference from the tool name.

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