Performance

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

The readOnlyHint=false annotation is backed up by concrete disclosure that trace_stop writes the full trace JSON to the artifact directory, which is exactly the write side effect an agent needs to know about. It also flags that full devtools fidelity requires a specific engine. No guidance on cost or duration of trace capture, and no auth or run-state requirements.

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?

Three tight sentences, front-loaded with the capability inventory followed by the trace lifecycle. Almost no filler, though the phantom engine advice consumes a sentence that earns nothing.

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 and zero schema description coverage, the description needs to explain what each action returns; it gestures at the vitals names and the trace artifact but leaves `limit` and most action semantics undefined. Adequate to make a first call, insufficient to use the tool well.

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 parameter meaning and largely does not: the `limit` parameter (1–200) is never mentioned, and the six action values are only loosely reflected in the feature list. Worse, the description instructs 'Use engine=chromium' for a parameter that does not exist in the schema, which is actively misleading about the input contract.

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 the resource (page performance data) and enumerates the concrete outputs: web vitals, CDP runtime metrics, slowest resources, overview, and Chrome trace. An agent can tell it is a measurement/diagnostics tool rather than a navigation or interaction tool. It stops short of a clean single verb-and-resource statement and never distinguishes itself from siblings like network or console.

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 trace_start → do work → trace_stop sequence is genuine procedural guidance that an agent would otherwise have to guess. However, there is no statement of when to prefer this tool over network, console, or status, and no prerequisites such as needing a page loaded or a Chromium engine attached.

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