list_processes

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

With no annotations provided, the description carries the full burden. It clearly implies a read-only operation ('List running BEAM processes') and describes the return type ('summary info'). While it doesn't explicitly state 'does not modify state' or mention permissions, the nature of the tool as a list/query operation is evident and sufficient for a simple read-only tool.

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 concise and well-structured: a brief purpose statement, a one-sentence summary of returns, and clearly labeled 'WHEN TO USE' and 'NEXT STEP' sections. Every sentence adds value without redundancy, and the format is front-loaded.

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?

For a list tool with four optional parameters, no output schema, and no annotations, the description adequately covers usage, return type at a high level, and next-step context. The only gap is that 'summary info' is vague about which fields are included, but given the tool's simplicity and sibling tools, this is acceptable.

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 100%, and the description adds little beyond the schema. It mentions sorting by memory or queue size, which aligns with the sort_by enum, but the schema already documents all four parameters with clear descriptions. Baseline 3 is appropriate since the schema does the heavy lifting.

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 verb 'List' and the resource 'running BEAM processes', and specifies what can be done (find by name, sort by memory or queue size). It effectively distinguishes itself from siblings like get_process_info, get_process_state, and get_process_dictionary by describing a summary-level discovery operation.

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 includes a dedicated 'WHEN TO USE' section that explicitly lists use cases: discovering processes, finding by name, or identifying high-memory/large-queue processes. It also provides a 'NEXT STEP' section naming specific alternative tools (get_process_info, get_process_state, get_process_dictionary), which is excellent guidance.

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