audit

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

The description goes well beyond the readOnlyHint, idempotentHint, and destructiveHint annotations. It discloses the exact data source path, the type of output (operation counts, risk highlights, recent entries, time range), and the honest limitations of rollback suggestions (create-class deletion, project.godot before_values, and Git reliance). It also mentions that write/destructive operations are auto-persisted via middleware with PII guardrails, providing a complete behavioral picture.

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 dense but compact, packing the core action, sub-actions, output summary, and middleware logging behavior into meaningful semicolon-separated segments. It is not overly long, and every sentence provides value, though clearer line breaks or bullet-like separation would improve scanability slightly.

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 five parameters, no output schema, and the already detailed input schema, the description provides comprehensive context: path, action-specific behavior, rollback limitations, and persistence expectations. An agent can correctly invoke both actions and understand the implications of the results without requiring additional missing information.

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 already covers all 5 parameters with descriptive comments, including action-specific meanings such as 'get_log:取末尾 N 条' and 'suggest_rollback:条目序号'. The tool description reinforces the actions but does not need to add much parameter meaning beyond the schema. This matches the baseline for a schema with 100% description coverage.

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 begins with '操作审计日志查询' (operation audit log query), clearly identifying a query action on a specific audit log resource. It further distinguishes two sub-actions: get_log for statistics and suggest_rollback for rollback suggestions, making the tool's purpose concrete and distinct from sibling categories like qa or validation.

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 specifies when to use each internal action: get_log for reading stats/history with time/count filters, and suggest_rollback for advising on specific logged entries. It also mentions that write/destructive operations are logged automatically, which hints at when audit data is available. It does not explicitly name alternative tools, but no sibling is a direct substitute, so this is sufficient.

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