probe_log

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes further: it discloses that only the tail is read and never the whole (possibly hundreds of MB) file, how encoding detection falls back utf-8 → utf-8-sig → gbk, and that reads do not consume the log. These are real behavioral traits beyond the annotation set.

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 operational content is front-loaded and correct, but a large block of the text is research justification ('of 7 surveyed bot projects, none used logs…') that does not help an agent decide or invoke. That padding dilutes an otherwise tight definition.

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, the description supplies the full return shape including encoding, total_lines_in_tail, matched_count, has_more and truncated_head, plus defaults for every parameter. An agent has everything needed to call and interpret results, even though structured fields are sparse.

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 carry all parameter meaning — and it does: path, pattern (regex, empty = all tail lines), max_lines (default 200, returns the *last* N), tail_bytes (default 262144 bytes). The 'last N lines' and 'tail bytes' semantics are precisely the non-obvious parts the schema omits.

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 verb+resource and scope: reads the *tail* of a game log and filters by regex, with automatic encoding detection. It also explicitly distinguishes itself from the sibling `drain_events` (non-consuming vs. consuming), so an agent can pick between them without opening either 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?

Explicitly gives the use case — repeated polling until a log line appears — and names the alternative (`drain_events`) plus the condition that separates them (consume-once vs. re-readable). It also states the negative-assertion use case (`matched_count` for 'no ERROR appeared'), which is a concrete when-to-use signal.

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