读取表达式 / 变量值

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds meaningful behavioral caveats beyond that: the target must be paused, a running target cannot be evaluated, and a value read immediately after hitting a breakpoint may be stale or dirty (e.g., PC=1), with advice to retry. This is valuable extra context an agent needs to interpret results correctly.

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 the core behavior and examples, followed by necessary caveats and then the parameter contract. Every section earns its place, including the alias list, which prevents agents from passing legacy parameter names. There is no filler or tautology.

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?

For a single-parameter, read-only tool with an output schema present, the description covers invocation syntax, example inputs, prerequisites, timing caveats, and the parameter contract. An agent has enough information to select and call this tool correctly without needing the output schema content.

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 exposes only a bare required string 'expr' with no description, so the description carries the full burden. It clearly explains what expr can contain (variable name, register, pointer dereference), provides multiple concrete examples, lists accepted aliases, and warns that unlisted parameter names are rejected rather than silently ignored.

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 opens with '计算并读取调试器中的一个表达式' and gives concrete expression forms such as 'SData_UA', 'timer.sec', and '*(uint32_t*)0x20000000', making the resource and verb clear. It does not explicitly contrast itself with siblings like read_variable or read_mem, so some differentiation is left implicit.

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 clear operational context: debug must be active, the target must be paused, evaluation is impossible while running, and values may be dirty immediately after a run-to-breakpoint with retry guidance. It does not name alternatives or explicitly state when to choose this tool over read_variable or read_mem, so full routing guidance is missing.

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