pix_get_cpu_samples

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

The description discloses the sampling mechanism (sampler interrupts, records when and on which core) and the key limitation (no instruction pointer, so call-stack resolution is not provided). This goes beyond the readOnlyHint annotation by explaining the data nature and what it can and cannot answer.

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 informative and well-structured, using a clear narrative to explain the purpose and limitations. It avoids unnecessary jargon and stays focused on the tool's behavior, though it is slightly verbose in explaining the sampling concept.

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 presence of an output schema (not shown in the input), the description still provides essential context about the data contents (samples, timestamps, core IDs) and the absence of instruction pointers. It is complete enough for an agent to understand the tool's role without additional documentation.

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?

Parameter names (capture_id, thread_id, start_time, end_time, limit, cursor_position, timeout_seconds) are self-explanatory, and the description mentions time-range aggregation. However, it does not explicitly explain the cursor, timeout, or limit semantics, so the agent must infer their meaning from common API conventions.

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 tool retrieves CPU samples for a specific thread, with one row per sample including timing and core information. It distinguishes this from related tools by explicitly noting it answers 'when' not 'where' (no instruction pointers), which separates it from analysis-focused 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?

The description explains the tool's output and its intended use case (measuring thread execution time and core distribution). It implies when to use it—when CPU sample data is needed—without explicitly naming alternative tools, but the context is sufficient for an agent to select it appropriately.

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