ACTION_PARSE_JSON

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

No annotations are supplied, so the description carries the full disclosure burden — and it does real work here: it enumerates the four output fields, states that every result is a string, and flags the counterintuitive edge case that a missing path yields the string value null while parse_success stays true. It also discloses ${var} interpolation and that results are returned as a variable snapshot, though it does not explain what happens to pre-existing variables on failure.

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?

Purpose is front-loaded in the first clause, followed by outputs and then edge cases — a sensible order with little waste. Minor blemishes: a duplicated sentence-ending punctuation mark ('。。') and slight redundancy between the null-path note and the general 'results are strings' statement.

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?

With no output schema and no annotations, the description adequately enumerates return fields and covers the important null-path edge case. What is missing is minor but real: whether output_var overwrites existing variables and how require failures surface to the agent.

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 100%, so the baseline is 3; the description goes beyond it by generalizing ${var} interpolation to all string parameters (the schema notes it only for json) and by clarifying the path parameter's failure semantics. It does not elaborate on require or on_error, which the schema already documents.

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 states a specific verb and resource ('解析 JSON 字符串并按路径取值') and names the exact output fields. The resource (JSON) alone distinguishes it from ACTION_PARSE_XML and ACTION_PARSE_DATETIME, so an agent can select it without opening the schema.

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 explains behavior but never says when to use this tool rather than alternatives (for example, extracting a field from an HTTP response, versus using ACTION_TEXT_OPERATION or ACTION_ARRAY), and it never names a when-not condition. Usage is implied by context, but no explicit guidance is provided.

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