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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the pre-configured port via env var, warns not to guess the port, and provides a concrete fallback procedure for debugging. This level of detail about connection prerequisites and failure handling is highly transparent.

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 appropriately sized for the tool's complexity, with each sentence providing valuable information: main purpose, port configuration, troubleshooting steps, and ordering requirement. It is front-loaded with the core purpose and avoids filler.

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 no output schema, the description covers the essential aspects: what it does, prerequisites, failure recovery, and ordering. The only gap is the lack of explicit statement about return behavior or idempotency, but for a connection tool, this is minor and the description is otherwise comprehensive.

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 tool has zero parameters, so the baseline is 4. The description adds significant context about how the connection is configured (via BEAM_SCOPE_MCP_PORT and Elixir config), which is directly relevant to invocation even though there are no explicit parameters. This goes beyond the empty 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 clearly states the tool's purpose: 'Connect to the BeamScope MCP server running in your Elixir application.' It uses a specific verb+resource and explicitly differentiates from siblings by noting it 'must be called before using other BeamScope tools,' making it distinct from status, logs, and eval 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 provides explicit when-to-use guidance: 'This must be called before using other BeamScope tools.' It also gives detailed troubleshooting steps for connection failures (check config files, .mcp.json). However, it does not mention alternatives or when not to use, which would push it to a 5.

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

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

With no annotations, the description carries the full burden. It discloses key behavioral traits: runtime vs disk config, inclusion of runtime.exs overrides, env var substitutions, and dynamic Application.put_env changes. This goes beyond a simple 'get' and helps the agent understand what to expect. However, it does not mention return format or error behavior, which is a minor gap.

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 well-structured and front-loaded. The first sentence defines the tool, followed by a useful clarification, then crisp WHEN TO USE/NOT FOR directives. Every sentence adds value with no fluff.

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 read-only config retrieval tool with no output schema, the description is complete. It explains the tool's scope, distinguishes it from disk config, provides alternatives, and implies the typical use cases. The absence of output schema is compensated by describing the content of the runtime config.

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%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides, but it does contextualize usage ('check config values for ports, feature flags, module settings'), which slightly reinforces the semantic meaning of app and key.

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 function with a specific verb and resource: 'Get runtime application configuration'. It distinguishes itself from similar tools by clarifying 'what the BEAM actually has loaded (not what's in the config files on disk)', which sets it apart from other inspection tools like get_system_stats and get_process_info.

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?

Explicit WHEN TO USE and NOT FOR sections are provided, naming exact alternatives for excluded cases: 'System health metrics (use get_system_stats)' and 'Process-level inspection (use get_process_info/state)'. This gives the agent clear routing guidance.

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

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

With no annotations, the description carries the transparency burden. It adds useful context about the BEAM_SCOPE_MCP_PORT env var dependency, but it does not describe what 'server details' includes, the expected return format, behavior when not connected, or whether the operation is purely read-only (though 'check' implies no side effects).

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 two sentences, front-loaded with the primary purpose in the first sentence. The second sentence adds a valuable configuration note without redundancy. No wasted words.

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 zero-parameter tool with no output schema, the description is decent but lacks specific return details—what exactly are 'server details'? It would benefit from listing fields like node name, port, or connection state. Without an output schema, the description should compensate, but it remains somewhat vague.

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?

There are zero parameters, giving a baseline of 4. The description correctly does not attempt to explain parameters since the input schema is empty, and no additional parameter semantics are needed.

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 function: 'Check if connected to an Elixir app and get server details.' This uses a specific verb ('check') and identifies the resource ('connection to Elixir app', 'server details'), distinguishing it from sibling tools like connect_beam_scope_mcp which establishes the connection.

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 usage context is implied: use when you need to verify connectivity. However, there is no explicit guidance on when to use this tool versus alternatives (e.g., connect_beam_scope_mcp), nor any mention of when not to use it. The additional env var configuration hint is helpful for setup but does not clarify tool selection.

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

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

No annotations are provided, so the description carries the full burden. It discloses that documentation is read from compiled .beam files and that no network access is involved, which are important behavioral traits. It could add more about error handling or return format, but the core behavior is well explained.

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 compact and well-structured with sections for purpose, when to use, not for, and examples. Every sentence contributes useful information, and there is no redundancy or filler.

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 simple 1-parameter tool with no output schema, the description covers purpose, usage constraints, examples, and exclusions. It provides sufficient context for an agent to select and invoke the tool correctly without needing additional information.

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 schema has 100% coverage for the single reference parameter, and the description adds substantial value by providing example formats (Module, Module.function, Module.function/arity, callback prefix). This gives the agent concrete syntax guidance beyond the schema's generic type definition.

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 identifies the tool as retrieving @moduledoc/@doc documentation for Elixir modules/functions. It specifies the resource (Elixir documentation) and distinguishes itself from siblings by noting it reads from compiled .beam files locally and is not for finding callers or evaluating code.

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 explicit 'WHEN TO USE' and 'NOT FOR' sections, naming alternatives like xref_callers and project_eval. It also clarifies the local-only nature (no network) and gives concrete usage examples, making it clear when to select this tool.

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

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

No annotations are provided, so the description carries full responsibility. It discloses that logs reside in a circular buffer and old entries may be discarded, which is a critical operational caveat. It also clarifies the tool is the sole log source and how grep/level filtering work. While it doesn't describe the exact return format, the disclosure is substantial.

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 well-structured with WHEN TO USE and NOT FOR sections, making it scannable. However, 'Your primary debugging tool' and 'Check logs before drawing conclusions from other tools' are somewhat redundant. Minor redundancy aside, every other sentence adds distinct value and there is no filler.

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 tool with 3 parameters, no output schema, and no annotations, the description fully equips an agent: it covers the tool's purpose, when to use it, how to filter, and a key behavioral caveat (circular buffer). It also prevents misuse by pointing to alternative tools. This is contextual complete for effective selection and invocation.

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%, so baseline is 3. The description adds practical guidance: recommends grep patterns (error, warning, timeout), explains level filters by severity, and implies tail returns entries from the end. This goes beyond the schema's terse property descriptions and helps an agent use parameters effectively.

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 it retrieves application logs from the running Elixir app, enumerating content types (errors, warnings, crash reports, application output). It also asserts this is the ONLY source of log data, distinguishing it from sibling tools. The verb 'Retrieve' plus the resource 'logs' is specific and unambiguous.

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?

Provides an explicit WHEN TO USE section: 'First step when diagnosing any problem' and 'Check logs before drawing conclusions from other tools.' It gives explicit NOT FOR scenarios with named alternatives: system resource usage → get_system_stats, process-level details → get_process_info. This clear directive leaves no doubt about when to choose this tool over siblings.

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

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

No annotations are provided, so the description carries the full burden. It discloses the dictionary's location, contains examples of entries, and notes it's a read operation ('Read'). It does not mention error handling for invalid PIDs or return format, but the scope is well explained.

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?

Description is compact and front-loaded with the core purpose. The WHEN TO USE / NOT FOR structure is highly scannable, and every sentence adds value.

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 simple read tool with one parameter, the description covers what, why, and when to use it, plus sibling differentiation. No output schema exists, but the description adequately sets expectations.

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% with a single well-described parameter ('PID string or registered name'). The description adds no extra parameter detail but doesn't need to since schema already fully documents it.

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 it 'Read the process dictionary' and explains it's hidden metadata outside main state. It explicitly distinguishes from siblings by listing what it contains (OTP internals like $ancestors) and what it's NOT for (main state, vitals).

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?

Provides explicit WHEN TO USE (metadata not in GenServer state, OTP ancestry, flags) and NOT FOR sections naming specific alternatives (get_process_state, get_process_info). This gives clear decision guidance.

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

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

With no annotations, the description carries the burden and largely succeeds: it communicates a read-only metadata operation and lists exactly what aspects are queried. It does not mention possible failure modes or whether it could block, but for a simple getter these are minor gaps, and the described behavior is transparent enough for typical agent use.

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 compact and well-structured, using bolding and section labels to front-load the core purpose. Every sentence serves a decision-making purpose—what it does, when to use, what not to use, and how to bootstrap the parameter—without redundancy or filler.

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 single-parameter metadata tool with no output schema, the description covers purpose, content, and usage disambiguation thoroughly. It omits explicit return format or error behavior, but the listed metadata categories and clear guidance make it practically complete for correct tool selection and invocation.

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 already gives 100% coverage for the single pid parameter, including format examples. The description adds a helpful tip to use list_processes for discovery, but this is contextual guidance rather than enriching the parameter's meaning. Baseline 3 applies for high schema coverage.

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 uses a specific verb ('Get') and resource ('metadata about a process'), enumerating exact content types (function, memory usage, queue length, links, monitors, stacktrace). It explicitly contrasts with sibling tools get_process_state and get_process_dictionary, making the purpose unmistakable and distinct.

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 an explicit 'WHEN TO USE' section ('identity and vital signs') and a 'NOT FOR' section that names the precise alternative tools for excluded cases. It also advises using list_processes first when the PID/name is unknown, giving clear actionable guidance for selection and sequencing.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds a critical caveat that the operation may timeout if the process is busy or doesn't support :sys messages, which is valuable for invocation planning. It doesn't cover all potential behaviors (e.g., side effects or process suspension), but for a read-only state retrieval that is sufficient.

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 well-structured with a concise lead sentence, then clearly labeled WHEN/NOT FOR sections, and a final note. Every sentence adds value and the text is front-loaded with the core purpose.

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 low complexity (two params, one output concept), the description is complete. It explains what data is returned, when to use it, when not to, and a limitation. No output schema is needed since 'state' is self-explanatory.

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 already fully describes both parameters (pid and timeout), providing a baseline of 3. The description adds behavioral context for the timeout parameter by noting it may timeout if the process is busy, connecting the parameter to real-world behavior. This elevates the score above baseline.

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 the internal state/data held by a GenServer process, using a specific verb ('Get') and resource (GenServer's loop state). It distinguishes itself from sibling tools like get_process_info and get_process_dictionary by explicitly narrowing scope to the internal data value.

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 explicit 'WHEN TO USE' and 'NOT FOR' sections with concrete alternatives, telling the agent when to use this tool versus get_process_info or get_process_dictionary. This directly addresses usage guidance and avoids ambiguity.

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

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

With no annotations provided, the description carries the burden of transparency. It discloses the recursive behavior ('Recursively walks supervisors'), the output content ('PIDs, types, and child counts'), and the prerequisite ('You MUST specify the app name'). While it does not explicitly state that the operation is read-only or describe error handling, the getter nature is implied and the behavioral description is informative enough for an agent to infer the tool's impact. This earns a 4.

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 two well-structured sentences: the first states core purpose with output detail, the second gives a prerequisite and a fallback discovery method. It is front-loaded, every sentence serves a distinct function, and there is no redundant or filler content. Perfectly concise for 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 the tool's simplicity, the description covers the essential context: what it returns (hierarchy with PIDs, types, child counts), the required input (app name), and a way to resolve the input if unknown. It does not mention behavior for unknown apps or when depth might be insufficient, but this is a minor omission for a getter tool. The output schema is absent, so the description's return-value hints are useful and adequate.

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%, with both parameters already described in the schema. The description adds value by emphasizing the app parameter's mandatory nature ('You MUST specify the app name') and providing guidance on how to find valid app names, which goes beyond the schema's field descriptions. It also reinforces the depth parameter indirectly through the demonstrated recursive behavior. This exceeds the baseline of 3.

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: 'Get the OTP supervision tree for an application.' It specifies the verb ('Get'), the resource ('OTP supervision tree'), and the scope ('for an application'), and goes further to describe what it does ('Recursively walks supervisors showing the full hierarchy of processes with PIDs, types, and child counts'). This distinguishes it from sibling tools like list_processes or get_process_info, which focus on individual processes rather than the hierarchical tree.

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 usage context: 'You MUST specify the app name' and gives a fallback approach for finding valid app names ('Use get_app_config or project_eval with Application.started_applications() to find app names if unsure'). This tells the agent when and how to use the tool, but it does not explicitly state when not to use it or name alternative tools for different scenarios. It's a minor gap, so a 4 is appropriate.

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

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

No annotations are provided, so the description carries the full burden. It discloses the specific data it returns, and it explicitly notes a limitation ('system stats don't show errors'). It does not explicitly state it's read-only, but the nature of the tool (health snapshot) and lack of parameters makes this clear. It could have added more about potential performance cost or frequency limits, but for a simple read-only tool, this is sufficient.

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. It front-loads the core purpose in the first sentence, then provides usage guidance in clearly labeled sections. Every sentence serves a purpose with no redundancy or fluff.

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 zero-parameter tool with no output schema, the description is complete. It explains what the tool does, what data it returns, when to use it, when not to use it, and its limitations. The sibling context further clarifies its position in the API. No additional details are necessary for an agent to select and invoke it correctly.

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 tool has zero parameters, so the input schema trivially has 100% coverage. The baseline for 0 params is 4, and the description correctly omits any parameter details since there are none. No additional semantics are needed.

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 with a specific verb ('Get') and resource ('BEAM runtime health') and lists the exact metrics returned (memory, scheduler count, process/port/atom counts, uptime, IO throughput). It effectively distinguishes itself from sibling tools like get_app_config, get_process_info, and get_logs.

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 explicit WHEN TO USE and NOT FOR sections with named alternative tools (get_app_config, get_process_info, get_logs), providing clear guidance on when to choose this tool over others. This is exemplary usage guidance.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It mentions that output is limited to avoid massive output, which is useful context. However, it does not elaborate on error behavior, return format, or clearly state it is a read-only operation (though 'Read' implies this). It adds some behavioral insight but not rich detail.

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 two sentences, efficiently conveying the core purpose, a warning about output limits, and a usage prerequisite. Every sentence earns its place with no wasted words.

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 simple read tool with two parameters, no output schema, and no annotations, the description covers the key aspects: what it does, the limit behavior, and the recommended workflow. It does not explain edge cases like nonexistent tables or exact row formatting, but these are not critical for a straightforward inspection tool. Overall, it is sufficiently complete.

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%, so the baseline is 3. The description does not add significant parameter-specific meaning beyond the schema; it only reiterates that output is limited, which is already captured by the 'limit' parameter description. Therefore, a 3 is appropriate.

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 reads and returns ETS table rows, using a specific verb and resource. It also distinguishes itself from the sibling tool 'list_ets_tables' by positioning itself as the follow-up step after listing table names, preventing confusion.

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 explicitly advises using 'list_ets_tables first to find table names, then inspect specific tables.' This provides clear context on when to use the tool relative to its sibling. However, it does not explicitly state exclusions or alternative tools for other scenarios, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently lists the metadata fields returned and the sorting order, making the tool's behavior predictable. It doesn't mention performance or side effects, but as a straightforward read-only listing tool, this is sufficient.

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 succinct and well-structured, with the main action and output fields in the first sentence, followed by a 'WHEN TO USE' and 'NEXT STEP' section. Every sentence provides useful guidance, with no wasted words.

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 simple zero-parameter tool with no output schema, the description is complete. It specifies what will be returned (metadata fields and sorting) and gives practical context for when to invoke it, plus a follow-up action. There are no gaps in understanding.

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?

There are zero parameters, and the schema coverage is 100% since it has no properties. The description doesn't need to explain parameters, and the baseline for 0 params is 4. It adds value by describing the output, which is more than enough.

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 lists all ETS tables with specific metadata fields (name, row count, memory, type, protection, owner) and mentions sorting by memory descending. This distinguishes it from sibling tools like inspect_ets_table, which reads table contents.

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?

It provides a 'WHEN TO USE' section explicitly stating the tool is for discovering existing ETS tables and finding the most memory-intensive ones. It also suggests a concrete next step (use inspect_ets_table), though it doesn't explicitly say when not to use it. This is clear context, just missing explicit exclusions.

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

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.

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

No annotations are provided, so the description carries the full burden. It discloses that code runs with full access to application modules, dependencies, and runtime state, which implies potential side effects. However, it stops short of explicitly warning about destructive operations or error handling, so a slight gap remains.

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 well-structured and front-loaded with the primary purpose, followed by a clear list of alternatives. Every sentence adds distinct value, and the bullet-point style improves scannability without verbosity.

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 that this is a general-purpose evaluation tool with no output schema, the description covers all essential context: what it does, when to use it, when to avoid it, what alternatives exist, and the level of access granted. It is sufficiently complete for an agent to decide and invoke correctly.

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 provides 100% coverage for both parameters (code and timeout) with clear descriptions. The tool description adds context that the code executes within the running application, but doesn't elaborate on parameter syntax, defaults, or edge cases beyond what the schema already states.

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 evaluates Elixir code in the running application context, using the specific verb 'Evaluate' and naming the resource. It differentiates itself as a general-purpose escape hatch, contrasting with specific sibling tools like get_logs and recompile.

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 explicitly tells when to use project_eval (one-off operations with no dedicated tool) and when not to, providing a list of preferred alternatives for common tasks like logs, process info, recompilation, ETS data, docs, and callers.

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

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

No annotations are provided, so the description must disclose behavior. It states the operation ('Recompile the entire project'), the context ('from within the running BEAM'), and the return value ('errors/warnings'). It adds that it is equivalent to 'mix compile'. It could go further by noting potential side effects like module reloading, but the core behavior is well disclosed.

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 clear one-sentence summary, followed by succinct 'WHEN TO USE' and 'NOT FOR' sections. Every sentence earns its place, zero waste.

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 parameterless tool with no output schema, the description provides sufficient context: what it does, when to use it, when not to, and what it returns. It also draws clear boundaries with sibling tools. No gaps.

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 tool has zero parameters and the schema coverage is 100% (empty schema). With no parameters, the description does not need to add parameter semantics, and the baseline for 0 params is 4. The description stays focused on behavior and usage.

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: 'Recompile the entire project from within the running BEAM.' It uses a specific verb and resource, and distinguishes itself from siblings by explicitly naming reload_module and recompile_deps as alternatives.

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?

Provides explicit WHEN TO USE and NOT FOR sections, naming specific alternatives (reload_module for single file changes, recompile_deps for dependencies). This gives clear guidance on when to select this tool over siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool force-recompiles dependencies (not the project) and emphasizes the mandatory args parameter. It does not mention side effects like clearing build caches or potential duration, but for a command wrapper this is acceptable. The 'MUST specify args' constraint is a behavioral trait beyond the mere schema required flag, adding some transparency.

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 two short sentences plus two labeled usage sections. It front-loads the core purpose, then gives actionable guidance. Every sentence earns its place with no fluff or redundancy.

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 single-parameter tool with no output schema, the description is sufficient. It covers the purpose, usage nuances, and explicitly names alternatives. It does not describe return values or failure behavior, but the tool acts as a wrapper around mix deps.compile, so the outcome is predictable. A 4 is warranted given no annotations or output schema to lean on.

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 already describes the only parameter (args) thoroughly with examples and meaning ('Args passed to mix deps.compile'). Schema coverage is 100%. The description merely repeats that args must be specified, adding little over the schema. Baseline of 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 tool's function: 'Force recompile Elixir dependencies (not the project itself).' The verb 'force recompile' plus the resource 'dependencies' and the scope exclusion 'not the project itself' precisely define the tool's purpose. It also distinguishes from sibling tools by explicitly naming alternatives in the 'NOT FOR' section.

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 explicit WHEN TO USE guidance (local path dependency source changed, or to force-rebuild a specific dep) and NOT FOR guidance (project code, with alternatives recompile or reload_module). This clearly tells the agent when to select this tool versus its siblings.

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

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

With no annotations, the description carries the full transparency burden. It discloses the hot-reload behavior and notes no full recompile is needed, which conveys the lightweight, runtime-mutating nature. However, it does not mention potential side effects (e.g., impact on running processes) or error behavior.

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 clear one-sentence purpose, followed by tightly scoped WHEN/NOT FOR sections. Every sentence contributes value with no redundancy.

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 simple single-parameter tool with no output schema or annotations, the description covers purpose, usage context, and exclusions. It does not explain return values or error handling, but that is not critical for a hot-reload utility and the guidance is otherwise complete.

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 already provides 100% coverage for the single 'file' parameter, including a detailed description with an example path. The tool description adds no additional semantic detail beyond what the schema provides.

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 uses a specific verb ('Hot-reload') and identifies the exact resource ('single module from its source file'). It distinguishes itself from sibling tools by naming alternatives like recompile and recompile_deps.

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?

Explicit 'WHEN TO USE' and 'NOT FOR' sections clearly state the ideal scenario and, importantly, identify alternative tools for other cases. This provides direct decision-making guidance.

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

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

No annotations exist, so the description carries the full transparency burden. It discloses that traces auto-stop with max_calls/max_seconds limits and clean up, and that this tool is for early cancellation. It also states it's safe to call with no trace running, implying no error or side effect. However, it doesn't explain what happens to trace data (e.g., partial results) or return value, but given the tool's simplicity, it provides sufficient behavioral context.

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 three sentences long and front-loaded with the action. The second sentence provides context on normal behavior (auto-stop), and the third covers the edge case of no running trace. Every sentence adds value with no fluff or repetition.

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?

The tool is simple: 0 params, no output schema, no annotations. The description covers the purpose, when to use it, the lifecycle context, and safety. It is reasonably complete for the tool's complexity. It might be improved by mentioning what the call returns or any side effects on trace data, but for a simple stop operation, the description provides enough context to use it correctly.

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 tool has 0 parameters, and the schema coverage is 100% (effectively nothing to cover). Per the rubric, 0 params results in a baseline score of 4. The description adds context about the trace lifecycle but no parameter details are needed. This is appropriate.

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 immediately states the tool's action: 'Abort a running trace early.' This is a specific verb+resource and clearly distinguishes stop_trace from its sibling trace_calls, which presumably starts traces. It also clarifies the trace lifecycle, making the purpose obvious.

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 explicitly explains when NOT to use the tool ('You do not normally need to call this') and when it IS useful ('if you want to cancel a trace before it finishes on its own'). It also notes that traces auto-stop and clean up, providing clear guidance for typical scenarios. Additionally, it mentions that it's safe to call even when no trace is running, which is helpful behavior guidance.

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

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

With no annotations, the description carries full behavioral disclosure. It reveals that the tool is asynchronous (writes to a file and returns a path), auto-stops after limits, and includes a sample log entry format. This is far beyond the bare minimum and gives the agent a clear picture of what to expect.

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 well-structured with clear sections (WORKFLOW, WHY A FILE) and is appropriately sized for the tool's complexity. Every sentence serves a purpose, and the key 'returns a file path' point is front-loaded. No wasted words.

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?

Without an output schema, the description fully explains the return value (file path), the file format, and the multi-step workflow. It also clarifies auto-stop behavior and resource limits. This is complete enough for an agent to use the tool confidently.

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 does not add meaning beyond the schema; it reiterates required parameters and caps that are already in the property descriptions. The example log line is a nice extra but doesn't change parameter semantics.

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 verb and resource: 'Start tracing function calls on a module.' It also distinguishes itself by explaining the key behavioral nuance that it writes to a file rather than returning results directly, which separates it from siblings like stop_trace or get_logs.

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 a detailed workflow (call, wait, read file) and states that stop_trace is not needed. However, it does not explicitly compare this tool to specific alternatives like get_logs or xref_callers, so the 'when to use vs alternatives' is only implied rather than directly stated. The workflow and notes on required params offer clear context.

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

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

No annotations are provided, so the description carries the full burden. It conveys the tool is a static cross-reference lookup ('across the project' and 'what depends on this?') and distinguishes it from runtime call flow via trace_calls. However, it does not explicitly state whether the operation is read-only or describe the output format, leaving minor gaps for an unannotated 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 compact and well-structured: main action in the first sentence, followed by WHEN TO USE and NOT FOR. Every sentence contributes value, with no redundant 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?

The tool has a single well-documented parameter, no output schema, and no annotations. The description covers purpose, usage context, and clear exclusions, making it sufficient for tool selection and invocation. The lack of output format details is a minor omission but not critical for this simple tool.

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 fully documents the only parameter, reference, with a clear description and examples. Since schema coverage is 100%, the description adds no additional parameter meaning beyond the schema, which aligns with the baseline of 3.

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 states the tool's specific verb and resource: 'Find all callers of a module or function across the project' and immediately clarifies the intent with 'what depends on this?'. This distinguishes it clearly from siblings like get_docs and trace_calls, which are explicitly named in the NOT FOR section.

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?

Explicit WHEN TO USE ('Impact analysis before refactoring') and NOT FOR sections, with named alternatives ('use get_docs', 'use trace_calls'), provide direct guidance on when to use this tool versus siblings. This leaves no ambiguity about tool selection.

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