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

Annotations already mark readOnly and non-destructive; the description adds substantial context: logs live ~1 hour, cover dev backend + live session only, empty if no editor open, includes background jobs, and describes the browser network line format. This far exceeds the annotation baseline and fully discloses the tool's scope and limitations.

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 long but extremely dense, with the 'FIRST step' hook front-loaded. Each clause adds new information (retention, source details, prod alternative). It is not a single-sentence terse statement, but it avoids redundancy and earns its length.

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 4 parameters (1 required), 0% schema coverage, and no output schema, the description is remarkably complete. It covers parameter semantics for two complex params, describes return contents, explains cross-referencing via log_reference_id, notes empty response conditions, and provides the alternative for prod logs. Nothing critical is missing for an agent to call this correctly.

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 compensate. It thoroughly explains 'source' (server vs. browser), 'log_reference_id' (pass from previous listing), and implies projectId via 'reads the project's runtime logs.' However, it never explains the 'limit' parameter (what it bounds, default, etc.) and projectId is only implied, not explicitly tied to the parameter. Two of four parameters lack direct treatment.

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 ('Reads') and resource ('project's runtime logs') and differentiates two modes (server and browser) with distinct contents. It also distinguishes itself from CloudWatch and directs to run_code_in_vm for published logs, making it non-confusable with siblings.

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 says 'Your FIRST step when debugging any runtime problem' and 'Call this before theorizing from an error message alone.' It also lists the alternative for published logs (run_code_in_vm's _floot.getProdBackendLogs) and even references get_guides for details. This is textbook when-to-use vs. when-not-to-use guidance.

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