tail_logs

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

No annotations were provided, so the description carries the full burden. It discloses the log location (~/.contextforge/logs/contextforge.log), that it's rotating, and enumerates the log content types. However, it doesn't mention that this is a read-only/non-destructive operation explicitly, nor does it describe the output format or what a tail operation entails beyond returning lines. Decent coverage but could add that it's a safe read in a persistent location.

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 two paragraphs, front-loaded with the core action in the first sentence, then enriched with valuable context about log location, rotating nature, and content types. Every sentence adds value — the log path is actionable, the rotating note explains why the tail is bounded, and the content enumeration tells the agent what signals it can extract. No filler or redundancy.

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 simple read operation with one well-documented parameter and an output schema present, the description is quite complete. It covers the log location, rotation behavior, content types, and the diagnostic purpose. The only gap is not stating the return format explicitly, but the presence of an output schema helps offset that. This is a strong, self-sufficient description for a tool of this complexity.

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%, and the single parameter (n, default 50) is well-documented in the schema itself with 'number of lines to return (default 50).' The description doesn't add much beyond what the schema already states about the parameter, so baseline 3 is appropriate. No parameter-specific enrichment in the description is needed given full schema 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 clearly states the verb (tail/return most recent lines) and the resource (persistent usage/debug log), and even details what log entries capture (tool invocations, pack assemblies, etc.). It also explains WHY the log matters (primary signal for tuning focus/governance behavior), which distinguishes it from the write-oriented sibling tools like append_context or upsert_context.

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 that this is the primary diagnostic signal for understanding real usage and tuning focus/governance behavior, giving clear context for when to use it. It doesn't explicitly name alternatives to exclude, but the purpose is distinct enough among siblings (most siblings are write operations, search, or entity management, whereas this is a read/diagnostic tool). Missing an explicit 'use X instead when...' but context is clear.

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