task_log

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

readOnlyHint=true already tells the agent this is a safe read, and the description usefully adds 'append-only' and 'JSON array' to convey immutability and payload shape. It omits behavior that materially matters for a log: event ordering, the default when no limit is given, and any cap on how far back the log goes.

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?

A single dense sentence with zero padding, and the core noun (the log) is front-loaded ahead of the filtering options. The parenthetical '(subtasks included)' is well placed, though the sentence crams three distinct filter modes into one clause chain.

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 tool with three undocumented optional parameters and no output schema, the definition is thin — it should say what a log event looks like and what the default result is with no filters. Since there is no output schema, the description is the only place that information could live, and it is only partly there.

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?

With 0% schema description coverage, the description carries the full parameter burden and partially delivers: 'task' maps to one task (with subtasks included), 'by' to one identity, 'limit' to the last N events. It never uses the parameter names explicitly and leaves open whether filters combine (AND) and whether 'last N' implies reverse-chronological order.

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 names a specific resource — the append-only mutation log — and states its return form (a JSON array), so the agent knows it retrieves history rather than mutating anything. It does not, however, contrast itself with siblings such as task_show or task_note, whose output could be confused with log data, so it stops short of a 5.

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?

Use is only implied: the optional filters suggest 'use this when you want the log for a task or identity,' but there is no explicit when-to-use, when-not-to-use, or named alternative among the many task_* siblings. The agent must infer that this is the history/audit path rather than the current-state path.

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