get_run_progress

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

With no annotations, the description carries the full disclosure burden and does: read-only and 'never touches or kills a process', observability side effects (observations written to the per-user state folder, not the run folder), the enumeration of possible `state` outcomes, and an explicit caveat that 'the ETA assumes a constant rate'. That is unusually complete behavioral context for a diagnostic tool.

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 safety note is front-loaded and every clause carries information, but the body is a single sprawling sentence dense with file-name jargon and a dangling 'Args:' line appended at the end. It is appropriately sized for the complexity but poorly structured for scanning.

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?

An output schema exists, so return values need not be spelled out, and the description still covers data sources, returned `state`, ETA caveats, hang detection, and error-block extraction. The remaining gap is the unexplained required `working_dir` argument.

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. It does explain `stale_minutes` operationally ('newest output file older than stale_minutes'), but `working_dir` is only listed in a trailing 'Args:' line with no statement of what directory it is (run folder? analysis folder?), leaving the required parameter semantically thin.

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?

States a specific resource (progress of a running or finished solve) plus which artifacts it reads (messag/mes0nnnn, d3hsp, lsrun.stdout.txt) and the `state` values it returns, so an agent knows exactly what it gets. It does not differentiate itself from near-siblings such as get_solve_status, check_run_health, or read_implicit_progress, which is the only thing keeping it from a 5.

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 gives implied usage for the ETA feature ('call it again a minute or more later') and the hang-hint conditions, which tells the agent how to use it, but there is no explicit when-to-use / when-to-prefer-an-alternative guidance against the many overlapping status tools in the sibling list.

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