get_performance_monitors

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

Annotations only declare readOnlyHint and destructiveHint, so the description carries the behavioral burden. It transparently discloses that values are real engine counters rather than estimates, that editor-target sampling windows are refused, and that duration_s>0 returns per-monitor min/avg/p95/max stats. This goes well beyond what annotations alone provide.

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 dense sentences with no filler. The resource and action are front-loaded, the key behavioral differentiator ('never estimates') appears early, and the pointer to help(tool=...) is a deliberate, useful routing rather than unnecessary prose.

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?

Given the 4-parameter schema, read-only annotations, and an output schema, the description covers the important choices: target mode, duration semantics, and the editor refusal. The only deferred content is the detailed sampling/refusal reasoning, but the description explicitly names the help command for it. A small omission is that the prose leaves out the 'auto' target value present in the schema, though the schema itself documents it.

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%, so the baseline is 3. The description additionally clarifies target's default behavior ('game default with a play session') and explains the consequence of duration_s>0 (sampling over time with per-monitor statistics). This is genuine added meaning, though interval_ms and series remain documented only in the schema.

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 opens with 'Profiling: read Performance monitors' and enumerates the exact metric families (fps, frame time, memory, counts, draw calls, video mem, physics), so an agent immediately knows the specific resource and verb. It also adds the qualitative distinction 'measured engine counters, never estimates,' which separates this from other read-style tools.

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 gives clear usage context: target can be game or editor, game is the default with a play session, duration_s>0 triggers time-sampled collection, and an editor-target window is refused. It points to help(tool=...) for the sampling rules and refusal reasoning. It does not explicitly name sibling alternatives, but the profiling context and target rules are enough to guide invocation.

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