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

The annotations already provide readOnlyHint and openWorldHint. The description adds context about the returned fields (caller ID, state, bridge, duration, dialplan location) which exceeds the annotations. However, it does not disclose behavior like potential latency, pagination, or the effect of the filter, so it remains moderate.

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 only two sentences, front-loaded with the enumeration of returned fields and ending with a crisp use case. Every word adds value, with 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 read-only listing tool with one optional filter, the description covers the key aspects: what data is returned, when to use it, and its live nature. It does not provide output structure details, but no output schema is present and the description sufficiently covers the tool's purpose.

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 description covers the sole parameter (filter) with a clear case-insensitive substring explanation and an example. The tool description adds no additional parameter guidance, but since schema coverage is 100%, the baseline of 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 lists active Asterisk channels with specific fields (caller ID, state, bridge, duration, dialplan location). It includes a memorable usage phrase, 'what calls are live right now', which distinctly positions it against sibling tools like asterisk_endpoints or asterisk_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 indicates when to use this tool: to see live calls ('This is the tool for 'what calls are live right now''). It implies a scenario for selecting this over others but does not explicitly list alternatives or exclusions, such as when not to use it.

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?

The annotations declare readOnlyHint=true, but the description states that setting PBX_MCP_ALLOW_WRITE=true lifts the read-only restriction, implying the tool can perform write operations. This directly contradicts the read-only annotation, so the contradiction rule applies.

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 and around 50 words, front-loading the tool's purpose and output format. Every sentence adds essential information: what it does, the default restriction, and how to change it.

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 CLI runner with no output schema, the description covers purpose, output, command restrictions, and configuration. It could mention the risk of enabling write mode, but overall it is sufficiently complete 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 schema description for 'command' already includes concrete examples (pjsip show endpoints, queue show support) and covers 100% of parameters. The tool description adds valuable semantic constraints by specifying that only inspection commands are allowed by default, which helps the agent select valid commands.

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 ('Run') and resource ('Asterisk CLI'), and clearly states that it returns raw output. It distinguishes itself from sibling tools by being the generic CLI runner for Asterisk, as opposed to the more specific status/channel/endpoint wrappers.

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 context: it is for inspection commands in the default read-only mode and only lists permitted command categories like 'core show', 'pjsip show', and 'queue show'. It also explains how to lift the restriction via PBX_MCP_ALLOW_WRITE=true, though it does not explicitly mention when to prefer sibling tools.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds minimal behavioral context beyond the schema, such as the optional narrowing to a single extension and the tracing use case, but does not describe return format or potential size of output. This is adequate but not rich.

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 concise sentences. The first states the core function, the second adds a practical use case. No redundant or filler content.

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 simple tool (2 params, 1 required), full schema coverage, and annotations covering safety, the description provides enough context for an agent to select and invoke the tool correctly. It lacks explicit output format details, but for a 'dump' action this is not critical. The tool is well-covered overall.

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 descriptions for both 'context' and 'extension'. The description paraphrases the schema ('for a context, or for one extension') but adds no new semantic details about parameter values or formats. Baseline 3 is appropriate since the schema already carries the parameter meaning.

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 ('dump') and clearly identifies the resource ('dialplan') and its scoping ('for a context, or for one extension within a context'). This clearly distinguishes it from sibling tools like asterisk_status or asterisk_channels, and adds a practical use case ('tracing where a call would go').

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 context for when to use the tool ('Useful for tracing where a call would go before placing it'), which implies a diagnostic scenario. It does not explicitly name alternatives or exclusions, but the sibling tools are clearly about different resources, making the appropriate use case reasonably clear.

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?

Annotations already declare readOnlyHint, and the description adds meaningful context by explaining the returned data (device state, registration counts) and the fallback to chan_sip peers on older installations. It does not, however, describe the output format or potential quirks, so transparency is adequate but not exceptional.

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-loads the core purpose, and then adds use cases and a fallback note. Every piece of information is useful and there is 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 list tool with one optional filter and no output schema, the description covers return content (device state, registered contacts) and a behavioral nuance (chan_sip fallback). It lacks explicit output fields or examples, but given the tool's simplicity, 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?

The schema has 100% coverage for the single 'filter' parameter, so the description does not need to add much. It doesn't provide extra meaning beyond the schema's description, but the high schema coverage makes the baseline of 3 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 lists PJSIP endpoints with device state and registered contact counts, and explicitly ties this to common queries ('is extension 1001 registered', 'which phones are offline'). It distinguishes itself from siblings like asterisk_channels and asterisk_status by focusing on endpoint registration rather than calls or system 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 explicit use cases for the tool, which gives the agent a clear context for when to invoke it. However, it does not explicitly mention when not to use it or name alternative sibling tools for other tasks, so it stops short of a full 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?

Annotations indicate readOnlyHint=true and openWorldHint=true. The description adds context by listing the specific status fields and the reachability use case, which goes beyond the annotations. It does not contradict the read-only nature, and no negative side effects are mentioned, which is consistent with a status read.

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 return content, and the second sentence provides actionable guidance. Every word earns its place; there is 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 simple status tool with no params, no output schema, and readOnly annotations, the description fully covers what the tool returns, how to use it, and its role among sibling tools. It is complete and self-sufficient.

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 does not need to explain parameter semantics, and the schema is fully covered. There is no missing parameter information.

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 specifies the resource ('Core status of the Asterisk server') and the exact fields returned ('version, uptime, active calls and calls processed'), making it clear this is a server-level status tool. It distinguishes itself from siblings like asterisk_channels and asterisk_endpoints by focusing on core server health rather than specific subsystems.

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 usage guidance: 'Use this first to confirm the PBX is reachable before running other Asterisk tools.' This tells the agent when to use it, but it does not explicitly name alternatives or state when not to use it, though the implication is clear.

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?

The description goes beyond annotations by disclosing the default read-only restriction, the PBX_MCP_ALLOW_WRITE environment variable to lift it, and the raw output behavior. This is meaningful additional context 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 two concise sentences: the first states the action and output, the second explains the permission model. No wasteful words, and important details are 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?

Despite having no output schema, the description covers the purpose, the permission restriction, how to override it, and the return format. It is complete for a command runner with one parameter.

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 the single parameter with examples, achieving 100% coverage. The description adds no extra parameter semantics, so the baseline of 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 verb and resource: 'Run a command through the FreeSWITCH event socket and return its raw output.' It also distinguishes from sibling tools by being the generic command runner, while siblings are specific read-only inspection commands.

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 context: it is a generic command tool with a default read-only mode, and lists example permitted commands. However, it does not explicitly mention alternatives or state when to prefer this over dedicated tools like freeswitch_status, so it lacks 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds context by clarifying that this is a live snapshot of all call legs, sourced from 'show channels', which reinforces the read-only, real-time nature. However, it does not disclose nuances like potential overhead of listing all channels, ordering, or behavior when there are no channels. This is adequate but not rich beyond 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 two sentences, both earning their place: the first defines the tool's output, the second gives its use case. It is front-loaded with the core function and uses precise, focused wording with no fluff or repetition. This is a model of conciseness.

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-only list tool with one optional parameter and no output schema, the description covers the essential context: what is returned (call legs), the source command ('show channels'), and when to use it (live calls). It does not detail the exact return format or pagination, but these are likely predictable from the underlying command. The description is sufficient for an agent to know what to expect and how to 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 schema has 100% parameter description coverage for the single optional 'filter' parameter, explaining it as a case-insensitive substring match. The description does not add any additional meaning about the parameter beyond the schema. Baseline of 3 is appropriate because the schema does the heavy lifting and the description's scope is on the tool's overall purpose rather than parameter syntax.

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: listing every call leg currently up on the FreeSWITCH switch, using the 'show channels' command. It explicitly frames this as the tool for 'what calls are live right now' on FreeSWITCH, distinguishing it from siblings like asterisk_channels. The verb 'list' is implicit in the title, and the resource and scope are 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?

The description gives a clear usage context: 'This is the tool for what calls are live right now on FreeSWITCH.' It does not explicitly mention when to avoid this tool or name alternative tools, but the emphasis on FreeSWITCH and the live-call scenario implies a distinction from Asterisk-based siblings. This is clear context without 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature and external changeability are known. The description adds behavioral context by enumerating the returned fields (contact URI, user agent, expiry) and the concept of Sofia profile, going beyond the annotations. No contradiction with annotations is present.

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, both essential: the first states what the tool does, the second provides practical use cases. It is front-loaded and contains no redundant wording. Every sentence earns its place.

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 with one optional parameter, annotations cover the safety profile, and the description specifies output fields and typical use cases. Despite lacking an output schema, the description enumerates the relevant return data, making it contextually complete for its complexity.

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 'profile' parameter, including a description of what it is and its default value. The description does not add any parameter-level meaning beyond what the schema already provides. Baseline of 3 applies because the schema fully documents the parameter.

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 registered SIP users on a Sofia profile with specific fields (contact URI, user agent, expiry). It distinguishes itself from sibling tools like freeswitch_channels and freeswitch_status by focusing specifically on registrations. The title 'List SIP registrations' is reinforced by the descriptive noun phrase.

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 gives concrete use cases: 'is this extension registered' or 'which devices dropped off'. This provides clear context for when to use the tool, though it doesn't mention alternative tools or exclusion scenarios. It lacks an explicit 'when not to use' clause.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description aligns with these by describing a read-only status query. It adds value by disclosing that it also reports whether trunks are registered upstream, which is a specific behavioral detail beyond a generic status read.

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?

Two sentences provide all essential information without redundancy. The main purpose is front-loaded, followed by a practical usage hint. 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?

Given the low complexity (one optional parameter, no output schema), the description covers the tool's purpose, the scope of its output (profiles and gateways with trunk registration), and the typical troubleshooting scenario. The schema documents the parameter, so nothing essential is missing.

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 only parameter, 'profile', is fully described in the schema ('Optional profile name for a detailed view instead of the summary.'). The description adds no further parameter-level nuance, so the schema carries the full burden, yielding the baseline score.

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: showing the state of every Sofia SIP profile and gateway, including trunk registration. It distinguishes from siblings by specifying the exact resource (Sofia profiles/gateways) and pairing this with a targeted use case (outbound call failures while the switch is healthy).

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 gives a clear contextual trigger: 'when outbound calls fail but the switch itself is healthy.' It does not explicitly name alternative tools or state when not to use, but the context strongly implies a diagnostic role separate from overall switch status.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds value by listing the specific status fields and noting the reachability check role. No behavioral surprises or omissions beyond what annotations cover.

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?

Two concise sentences—one listing the returned fields, one providing usage guidance. 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?

For a simple, no-parameter status tool, the description fully covers what it returns and when to use it. The absence of an output schema is compensated by listing the exact fields. Sibling context is well handled.

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 is empty with 100% coverage. With no params to describe, the description does not need to add parameter details; baseline for zero-param tools is 4.

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 provides 'Core status of the FreeSWITCH server' with specific fields (version, uptime, sessions), distinguishing it from sibling tools like freeswitch_channels or asterisk_status. The intent to check server reachability is explicit.

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 guidance: 'Use this first to confirm the switch is reachable before running other FreeSWITCH tools.' This tells when to use and implies alternatives for more specific checks.

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