get_run

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already establish this as a safe, non-mutating read. The description adds that the record is 'compact' and 'dashboard-oriented,' implying a summarized or trimmed representation, which is honest about the return shape. However, it doesn't disclose pagination, size limits, or whether the record contains temporal snapshots vs current state.

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?

A single, compact sentence with zero wasted words. Front-loaded with the action verb 'Return' and immediately states the resource. At this length, it is optimally concise.

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 a single parameter, decent annotations, and an output schema. For a simple retrieval tool, the description is near-sufficient. However, with the meaningful qualifier 'dashboard-oriented,' some elaboration on what fields/scope differentiate this from get_run_view or get_run_result would help. The output schema exists, so return values need not be explained. Given the 0% schema coverage on its one parameter and no differentiation guidance, a middle score is appropriate.

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 for the undocumented run_id parameter. The run_id is self-explanatory as an identifier, but given it's the sole parameter, the description could note what format is expected (UUID, numeric, etc.) or that it must reference an existing run. The description adds zero parameter-level information.

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 says 'Return a compact dashboard-oriented run record.' This identifies the verb (return) and resource (run record) but the qualifier 'compact dashboard-oriented' is somewhat vague. It does not clearly differentiate from siblings like get_run_view, get_run_result, get_run_events, get_run_control, which all return run-related data but likely with different scopes/purposes. The purpose is clear enough as a retrieval tool but lacks specificity about what 'dashboard-oriented' means.

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?

No guidance is given about when to use this tool versus alternatives. With numerous sibling tools (get_run_view, get_run_result, get_run_control, get_run_events), the description provides no context for choosing get_run over them. 'Dashboard-oriented' hints at a use case but does not explicitly state when this should be preferred over the detailed/results/control variants.

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