get_performance_monitors

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

The description goes far beyond the readOnlyHint annotation by disclosing that counters are measured, never estimates, that duration_s polls while the game keeps running, that series=true is token-heavy, and that editor-target sampling is refused because it would stall the editor. These are valuable behavioral traits not present in the annotations.

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 moderately long but every sentence contributes unique information. It is front-loaded with the core purpose, uses clear formatting (e.g., SAMPLES OVER TIME, stats list), and includes a concrete example (fps.p95) without redundancy. The length is justified by the tool's complexity.

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 four parameters, no output schema, and only read-only annotations, the description is fully complete: it explains return stats ({min,avg,p95,max}), target modes, sampling mechanics, limits, optional raw series, and the editor refusal edge case. An agent can confidently invoke this tool in various scenarios.

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?

Although schema descriptions cover all four parameters, the description enriches them significantly: it explains target default behavior (game when a play session is connected), that duration_s is game-only with max 30, the default and minimum interval, and that series=true returns raw samples with token-heavy implications. This adds meaning well beyond 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' followed by an explicit list of metrics (fps, frame time, memory, object/node counts, draw calls, video mem, physics), giving a specific verb and resource. It clearly distinguishes itself from siblings like get_project_statistics and monitor_properties by focusing on engine counters and sampling behavior.

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 clearly states when to use the tool (profiling, game vs editor target) and explicitly describes when not to use it: editor-target over-time sampling is refused because it would block the editor loop. It does not name alternative sibling tools, so it lacks an explicit 'use X instead' comparison, but the context is unambiguous.

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