prepare_profiling

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

With no annotations, the description carries the full burden. It explains that the tool retrieves a parameter and that the parameter should be added quoted, and records performance data with stack traces for listed subsystems. However, it does not disclose potential side effects, authentication needs, rate limits, or the behavior if called multiple times. This is adequate but could be more comprehensive.

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 extremely concise: two sentences that front-load the purpose and subsystems, then explain the output and next step. Every word contributes value, and there is no redundant or unnecessary information.

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 tool's complexity (profiling session with multiple subsystems, optional parameters, and coupling with check_status), the description covers the essential points: purpose, subsystems, output format, and required follow-up action. It could benefit from an example of the jvmParameter or mentioning what happens if delay or maximumDuration are omitted, but it is adequate for a tool with no output schema and 100% parameter coverage.

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?

The input schema descriptions for 'delay' and 'maximumDuration' are clear, and the tool's description adds valuable context: delay is from JVM start, and maximumDuration defaults to saving at termination or when check_status with stopRecording=true. This enhances understanding beyond the schema alone.

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's purpose: preparing a profiling session by retrieving a JVM parameter for specific subsystems (cpu, jdbc, jpa, etc.). It specifies the output (JSON with 'jvmParameter') and distinguishes it from siblings by detailing the subsystems and post-call action (check_status).

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 provides clear guidance on when to use the tool (before starting a Java process) and directs the user to call check_status afterwards. However, it lacks explicit when-not-to-use instructions or direct comparison with sibling tools like 'attach' or 'get_performance_hotspots'.

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