get_run_progress

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

No annotations are provided, so the description carries the full burden. It does well by disclosing that it reads runme.log and reports the last log update time to judge whether Vivado is active. It also enumerates the types of information returned. While it doesn't explicitly state 'read-only', the 'get' prefix and progress-monitoring intent make that implicit.

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 well-structured with a one-line summary, a bulleted list of what the tool returns, and a clear 'Args' section. Every sentence provides useful information without redundancy. It is appropriately detailed for a tool with three parameters and no annotations.

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?

Given the tool's relatively simple purpose and the presence of an output schema, the description is complete. It explains the use case, what data is shown, and parameter meanings. It also provides enough context to differentiate it from sibling tools like get_critical_warnings, even though it does not name alternatives explicitly.

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 fully explain parameters. It does: run_name is described with examples and default ('synth_1'/'impl_1'), tail_lines is defined as how many log lines to read, and session_id is identified as the target session ID. All three parameters are meaningfully documented beyond their schema names.

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 the tool's purpose: '查看 run 的运行进度' (view run progress) and elaborates with a specific use case ('适合长任务等待时看走到哪一步'). It lists concrete outputs (status, progress percentage, phases, log tail, update time), distinguishing it as a monitoring/read tool rather than a synthesis/implementation action.

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 explicitly states when to use: during long-running tasks (10-30 minutes) when you want to check progress without opening the GUI. It does not explicitly contrast with alternatives like get_critical_warnings, but the context is clear enough for an AI agent to select this tool for progress checks.

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