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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-state dependence are covered. The description usefully adds that results are a live snapshot of channels that are "currently up" and what each row contains, but says nothing about truncation, latency, or whether the read touches the switch in a way that could be slow on large PBXs.

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 short sentences, no redundancy, and the returned-field list comes first with the usage cue last. Every clause carries information an agent can act on.

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 no-parameter, read-only list tool with no output schema, the description does the necessary work by naming the returned fields and framing the result as a current snapshot. It stops short of noting whether the list can be very large or how errors from an unreachable PBX surface.

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 single filter parameter is documented as a case-insensitive substring match against any field. The description never mentions filtering at all, so it adds nothing beyond the schema; baseline 3 applies.

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?

Names a specific resource (live channels on the Asterisk PBX) and enumerates the fields it surfaces (caller ID, state, bridge, duration, dialplan location), which tells an agent exactly what it gets back. It does not explicitly contrast with freeswitch_channels, relying on the platform in the name to separate the two siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The line "This is the tool for 'what calls are live right now'" gives a clear triggering question, which is stronger than most list tools. However it states no exclusions or follow-on routing (e.g. to asterisk_hangup_preview before dropping a call, or to freeswitch_channels for the other platform).

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 and destructiveHint=false, but the description says setting PBX_MCP_ALLOW_WRITE=true lifts the read-only restriction, permitting write commands. That conditional write capability contradicts the static read-only and non-destructive 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 three sentences, front-loaded with the core action and output behavior, then the default permission restriction and override. Every sentence adds useful context with 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 one-parameter tool with full schema coverage, the description covers the action, raw output, and permission modes. It is adequate, though it could say more about invalid-command behavior, output size, and when generic CLI use is preferable to a specialized sibling.

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 schema itself already documents the single command parameter with examples. The description adds permitted-command examples but does not add syntax, format, or semantic details beyond what the schema provides, so the baseline 3 applies.

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 a specific verb and resource: running an Asterisk CLI command and returning raw output. It does not distinguish this generic escape hatch from more targeted siblings such as asterisk_channels, asterisk_endpoints, or asterisk_status, so it falls short of a 5.

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 gives clear operational context: default read-only mode, permitted inspection command families, and the PBX_MCP_ALLOW_WRITE override. However, it does not explicitly say when to prefer specialized sibling tools over this generic CLI tool, leaving alternative selection to inference.

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 safety profile is covered. The description adds the purpose (call-path tracing) but says nothing about output volume or shape, which matters for a "dump" operation that can return a large dialplan; no pagination or truncation behavior is 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?

Two short sentences, zero filler, with the primary scoping behavior front-loaded and the use case trailing as supporting context.

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, two-parameter inspection tool with full schema coverage and no output schema, the description covers what the agent needs to select and call it. A brief note on expected output size for large contexts would close the remaining gap.

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%, with both `context` and `extension` documented including an example context value. The description only restates that extension narrows the output, so it adds no semantics beyond the schema; baseline 3 applies.

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?

States a specific verb (dump) and resource (dialplan) and immediately clarifies the two scoping modes: whole context or a single extension within a context. That precision is enough to distinguish it from every sibling, which all target entirely different resources (channels, endpoints, registrations, 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?

Gives a concrete use case — tracing where a call would go before placing it — which tells the agent when this tool is the right choice. It stops short of naming alternatives or stating exclusions, so it is clear context without full 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: it falls back to chan_sip peers on older installations, which changes what the returned data means. It does not describe result ordering or volume, 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?

Three short sentences: what it returns, when to use it, and the fallback caveat. Every sentence earns its place and the payload description 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 read-only, single-optional-parameter listing tool with no output schema, the description covers the returned fields, the intended question types, and a platform-variance caveat. Nothing needed to call it correctly 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?

Schema description coverage is 100% and the single optional 'filter' parameter is already documented as a case-insensitive substring match. The description never mentions filtering, so it adds nothing beyond the schema, but the baseline of 3 applies when the schema carries the 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?

Names a concrete resource (PJSIP endpoints) and the attributes returned (device state, registered contact count), so the agent knows exactly what comes back. It differentiates itself from asterisk_channels implicitly via the registration/device-state framing, but never names a sibling tool to contrast with.

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 two concrete question templates ('is extension 1001 registered', 'which phones are offline') that map cleanly onto the tool, which is strong contextual usage guidance. It stops short of saying when NOT to use it or which sibling (e.g. freeswitch_registrations, asterisk_channels) to pick instead.

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, so the non-mutating nature is partly redundant, but the description adds real value: it explains the matching behavior (exact match plus near misses) and the read-only-mode availability, which annotations do not convey. It stops short of describing output shape or limits on the near-miss list.

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?

Three short sentences, front-loaded with the core action, then the blast-radius rationale, then the availability caveat. No filler and nothing buried mid-sentence.

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 read-only preview with no output schema, the description covers what it does, what it returns at a high level (exact match plus near misses), and its availability constraints. Nothing an agent needs in order to call it correctly 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?

Schema coverage is 100%, so baseline is 3, but the description adds matching-resolution semantics — that the single channel argument yields an exact match plus near misses — which the schema does not state. It also pins the argument as identical to asterisk_hangup's, which helps an agent reuse a known value.

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?

States a specific verb and resource: 'Show which live channels a hangup would affect, without touching them.' The preview-vs-execute distinction from the sibling asterisk_hangup is explicit, so an agent can pick between them without inspecting schemas.

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?

Explicitly routes usage: 'see the blast radius before dropping a call,' and names asterisk_hangup as the tool it mirrors ('takes the same channel argument as'). It also states the precondition-free case ('Always available, including in read-only mode'), leaving little to infer.

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?

Annotations cover the safety profile, but the description adds the conditional write-gate behavior (env var opt-in) that the static readOnlyHint cannot express, plus the fact that output is raw/unparsed. It does not mention error formats or payload size limits, which keeps it below a 5.

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?

Three short sentences, zero waste, with the core action and return value front-loaded ahead of the permission caveat. 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?

For a single open-ended string parameter with no output schema, the description covers the essential unknowns: it is a pass-through to the event socket, output is raw, and a permission gate may cause rejection. Only the failure/timeout behavior is left unaddressed.

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 schema already supplies concrete examples ('show calls', 'sofia status gateway mytrunk'), so the description need not document the single parameter. It adds nothing about the command string's syntax or quoting that the schema lacks, so baseline 3 applies.

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?

States a specific verb and resource ('Run a command through the FreeSWITCH event socket') plus the return characteristic ('raw output'). It is distinguishable from the narrower siblings like freeswitch_status or freeswitch_channels as the generic escape hatch, though it never names them explicitly.

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?

Adds a real usage rule: in the default read-only mode only inspection commands such as 'status', 'show', 'sofia status' are permitted, and PBX_MCP_ALLOW_WRITE=true lifts the restriction. That tells the agent when a call will be rejected, but it doesn't route the agent to the specific-purpose siblings when those would be more 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and openness are covered. The description adds that output mirrors 'show channels' and is a live snapshot rather than historical, but says nothing about output shape, volume, or refresh cadence.

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, no filler, and the identifying characteristic (live call legs) comes first. Every clause carries information an agent can act on.

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?

A one-parameter, read-only listing tool with full schema coverage and annotations needs little more than this. Only the absence of any note on result size or relationship to the other FreeSWITCH status tools keeps it from a 5.

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 single optional 'filter' parameter is fully documented in the schema, including substring-matching semantics. The description adds nothing about parameters, so baseline 3 applies.

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?

States a specific resource and scope: 'every call leg currently up on the switch', qualified as FreeSWITCH and tied to the 'show channels' source. This implicitly separates it from the Asterisk siblings (asterisk_channels), though it never names them directly.

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?

Gives a clear selection rule: 'the tool for what calls are live right now'. It stops short of exclusions — it doesn't say when to prefer freeswitch_status, freeswitch_sofia_status, or freeswitch_registrations instead.

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 the description reinforces this with 'without touching them' and the read-only-mode note, then adds genuinely new behavioral detail: it reports the matching channel plus the leg it is bridged to. It does not describe behavior when the UUID matches nothing or how ambiguous partial matches are resolved, which is the remaining 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?

Three short sentences, zero waste. The non-destructive nature and blast-radius framing are front-loaded, and the availability note is placed last where it belongs as a caveat.

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 one-parameter read-only preview with no output schema, the description covers purpose, safety, return content ('the matching channel plus the leg it is bridged to'), and availability. The one missing piece is what the caller sees when nothing matches or when the partial UUID is ambiguous, which matters for a preview tool whose whole job is reporting.

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% and the schema already documents the single uuid parameter, including partial-match support ('or part of one'). The description adds only that it is the 'same UUID argument as freeswitch_hangup', which is a useful consistency cue but not new semantics. Baseline 3 applies.

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?

States a specific verb and resource ('Show which live call legs a hangup would affect') and immediately distinguishes itself from the mutating sibling by noting it does so 'without touching them' and takes 'the same UUID argument as freeswitch_hangup'. An agent can tell it apart from freeswitch_hangup without opening either schema.

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?

Gives clear context for when to reach for it: 'so you can see the blast radius first', i.e. before calling freeswitch_hangup, plus an availability note ('Always available, including in read-only mode') that tells an agent it can call this even under restrictive conditions. It stops short of explicitly naming when not to use it or naming the asterisk_hangup_preview sibling as the alternative for the other stack.

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 safety profile is covered. The description adds the returned field set, which is valuable given there is no output schema, but it says nothing about whether the snapshot is live, how staleness is handled, or how large the result set can be.

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 tight sentences with zero filler; the returned-field summary comes first and the use-case framing second, so the agent gets the essentials immediately.

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 read tool with no output schema, the description does the important work of naming the return fields. Minor gaps remain around result ordering, pagination, and liveness, which matter for a registration list an agent may need to reason about.

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% and the profile parameter is fully documented in the schema, including its default. The description's phrase "on a Sofia profile" merely restates the filter without adding semantics such as what happens when an unknown profile is supplied, so baseline 3 applies.

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 names a specific resource (registered SIP users on a Sofia profile) and enumerates the fields returned (contact URI, user agent, expiry), so the agent knows exactly what comes back. It does not, however, differentiate itself from the closest sibling, freeswitch_sofia_status, leaving ambiguity about which to pick.

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?

Two concrete example questions ("is this extension registered", "which devices dropped off") give a clear picture of the situations this tool serves. There are no explicit exclusions or named alternatives, so the agent must infer when to prefer freeswitch_sofia_status or asterisk_endpoints instead.

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 safety is covered. The description adds real value beyond that by previewing the returned content (profile/gateway state plus upstream registration) and framing the failure scenario it diagnoses, which matters since there is no output schema.

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, no filler, with the resource and the diagnostic use case both front-loaded. Every clause 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?

For a single-optional-parameter read tool with annotations and no output schema, the description covers purpose, returned content, and diagnostic context. Only the shape of the detailed (per-profile) view is left unstated, a minor gap.

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% and the single optional 'profile' parameter is fully documented there, including the summary-vs-detailed distinction. The description says nothing about the parameter, so it neither adds nor detracts; baseline 3 applies.

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?

Names a specific resource (every Sofia SIP profile and gateway) and a concrete state (upstream trunk registration), which is more precise than the sibling freeswitch_status. It differentiates implicitly via the 'switch itself is healthy' framing rather than naming the sibling, so it falls just short of 5.

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?

Gives a clear diagnostic trigger: 'where to look when outbound calls fail but the switch itself is healthy.' That condition also implies when not to use it (generic switch problems belong elsewhere), though no sibling is named explicitly.

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.