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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful context beyond the annotations: the default response is a truncated structural summary due to the config's large size, and section/raw override that behavior. This goes beyond the schema's basic parameter semantics.

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 sentences: default behavior, parameter option, and raw caveat. Front-loaded with the core purpose and immediately guides the agent to the best default call. Every sentence carries operational 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 read-only, optional-parameter tool with 100% schema coverage and an output schema, the description covers the default behavior, the override options, and the rationale. An agent can call this correctly without further documentation.

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 documents the section values including 'raw' and omission behavior. The description adds practical selection guidance (prefer summary over raw unless full JSON needed) and clarifies output scale, which enhances the schema without repeating it verbatim.

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 (Reads) and resource (Xray core configuration), and distinguishes the default structural summary from full raw output. This clearly differentiates it from sibling tools that target hosts, nodes, subscriptions, inbounds, or users.

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 advises when to omit the parameter vs pass a section, and explicitly cautions against using "raw" unless full JSON is truly needed. The schema description echoes this guidance, reinforcing the decision rule.

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 mark the operation as read-only and non-destructive. The description goes beyond this by explaining the grouping behavior and, importantly, that unknown template tokens are flagged rather than causing an error because Marzban leaves them un-substituted. This gives an agent useful insight into output semantics that annotations cannot convey.

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 carry all the essential information without redundancy. The core listing behavior is front-loaded, and the secondary token-flagging behavior is added in a compact, useful second 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 zero-parameter, read-only tool with an output schema available, the description is complete. It explains what is returned, how results are grouped, and what the notable edge-case behavior is. There are no outstanding gaps an agent would need filled 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 tool has zero parameters, and the schema coverage is 100%, so there are no parameter semantics to document. The baseline of 4 applies here: the description appropriately focuses on the returned data and behavior rather than inventing parameter guidance.

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 ('Lists'), a concrete resource ('proxy host settings'), and a distinguishing organizing principle ('grouped by inbound tag'). It also adds a second specific behavior (flagging unknown `{VARIABLE}` tokens) that makes the tool's purpose unmistakable and separates it from generic config or inbound 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 makes the tool's purpose clear, so an agent can infer it is the right choice for inspecting proxy host settings. However, it does not explicitly state when not to use it or which sibling tools should be preferred for related concerns such as general config, inbound management, or node 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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that it lists only connected nodes, includes status and Xray version, and that bandwidth usage is scoped to the given period, defaulting to all-time when both parameters are omitted.

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 with no filler. The main purpose and return contents are front-loaded, and the parameter semantics are stated compactly and clearly.

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 operation with zero required parameters and an existing output schema, the description covers the essential behavior, parameter semantics, and default period. Nothing critical is missing for an agent to select and invoke this tool 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?

Schema description coverage is 100%, so the baseline is 3, and the description goes further by explaining that start/end narrow the bandwidth usage window rather than filtering nodes, and explicitly stating that omitting both parameters gives all-time usage. This adds meaning beyond the schema's generic 'no lower/upper bound' phrasing.

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 ('Lists'), names the resource ('all connected nodes'), and enumerates exactly what is returned: status, Xray version, and bandwidth usage over a period. This clearly differentiates it from sibling tools like marzban_system_stats or marzban_hosts_get, which target different resources or aggregates.

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 parameter usage guidance ('omit both for all-time') but does not explicitly state when to prefer this tool over sibling tools or mention any exclusions. The use case is implied rather than directly contrasted with alternatives.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: this uses the same public, unauthenticated endpoint that client apps use, requires no username, and operates on a subscription token rather than an admin/session token. This enriches the agent's understanding beyond 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?

Two sentences with no filler. The primary action and key constraint are front-loaded, and the sibling tool comparison is integrated naturally. 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?

Given the tool's simplicity (one parameter), full schema coverage, output schema presence, read-only annotations, and explicit sibling differentiation, the description is complete. Nothing an agent needs to call this 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%, so the schema already fully documents subscriptionToken, including its location in the URL and its distinction from admin tokens. The description reinforces that the token comes from a subscription URL, but adds no meaning beyond what the schema already provides; the baseline of 3 is appropriate when the schema carries the parameter documentation burden.

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 ('Reads'), a specific resource ('subscription status/usage/expiry'), and the required input ('token from a subscription URL'). It also explicitly differentiates itself from the sibling tool marzban_users_get, so an agent can select it correctly without ambiguity.

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 use case: diagnosing a broken subscription link without needing the username. It also names the alternative tool and the condition for using it ('admin-side lookup by username, use marzban_users_get instead'), providing explicit when-to-use and when-not-to-use 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=true and destructiveHint=false, so the read-only safety profile is covered. The description adds scoping detail about what is included (configured inbound proxies, grouped by protocol) and that it is not raw JSON, but does not disclose additional behavioral traits such as response size or potential filtering.

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 with no filler. The primary purpose and returned fields are upfront, and the alternative tool is mentioned in the second sentence without distracting from the main definition.

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 read-only list operation with annotations, an output schema, and a clear sibling alternative, the description is fully sufficient. Nothing essential is missing for an agent to select and invoke the tool 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?

There are zero parameters, so the schema has no parameter semantics to document. The description instead clarifies the shape and scope of the returned data, which is useful context and matches the baseline for a parameterless tool.

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 the specific verb 'Lists' and a precise resource ('configured inbound proxies'), then details the returned fields (tag, network, TLS mode, port) and grouping by protocol. It also explicitly distinguishes itself from the raw Xray inbound JSON returned by marzban_config_get.

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 a clear when-to-use this tool versus the alternative: use this for a structured summary, use marzban_config_get with section 'inbounds' when raw Xray JSON is needed. This explicit routing removes ambiguity for the agent.

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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating exactly what the tool reports, including live Xray running state, which goes beyond the basic 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?

A single sentence that front-loads the main purpose and then packs the key reportable items into a compact list. Every phrase adds information without 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 zero-parameter, read-only stats endpoint with an output schema present, the description is fully sufficient. It tells the agent what category of data to expect, and the annotations cover the operational risk profile.

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 there is no parameter semantics to document. The description correctly does not invent any parameters, and the schema's empty properties are consistent with that.

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 opens with a specific verb and resource: 'Reports panel-wide stats', then enumerates the concrete data categories covered (CPU/memory, user counts, bandwidth, Xray core status). This clearly distinguishes it from siblings like marzban_system_inbounds or marzban_users_list.

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 implies usage for obtaining an overall panel health/statistics overview, but it does not explicitly state when to prefer it over alternatives or mention any exclusions. There is no direct comparison to sibling tools such as marzban_system_inbounds.

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 mark this as a non-read-only, non-destructive operation. The description states the concrete effect ('status to active') but adds no further behavioral context such as idempotency, effect on subscription data, or failure conditions. There is no contradiction with 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?

One short, front-loaded sentence with no filler. Every word contributes to communicating the tool's purpose, and the description is an model of concise structure.

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 state-transition tool with an output schema and basic annotations, the description is mostly sufficient: the target and action are clear. It omits optional behavioral details such as idempotency or interaction with deactivated/held states, but these are not required for a correct call.

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 provides only the username property name and constraints, with no parameter description, and the tool description does not explicitly explain the username parameter's role. Still, the phrase 'a user's status' implicitly ties to the single username parameter, so the meaning is recoverable even though the description adds little beyond the 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 uses a specific verb ('Sets') and a concrete resource/outcome ('a user's status to active'), clearly distinguishing it from the sibling marzban_users_deactivate and marzban_users_hold tools. It is not a tautology and names the exact state transition.

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?

No explicit when-to-use or when-not-to-use guidance is provided, and no alternative tools are named. However, the action word 'activate' and the sibling set make the intended context reasonably inferable, which is the boundary between 'implied use' and 'no 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?

The description discloses meaningful behaviors beyond the annotations: omitted dataLimit and expire default to unlimited, and explicitly provided fields override template values. This helps agents predict side effects without contradicting 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?

Two compact, information-dense sentences with no wasted words. The most important defaults and template behavior are communicated without burying 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 complex 10-parameter schema and rich nested properties, the description covers the key non-obvious behaviors and relies on the schema for remaining parameter details. The main gap is not mentioning that omitting proxies uses server defaults on create, though the schema covers this.

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?

With 70% schema coverage, the description adds real interpretive value for dataLimit, expire, and templateId, including human-readable sizes, relative durations, absolute dates, and template override semantics. It does not cover every optional parameter, but the schema already documents most of them well.

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+resource — 'Creates a new user' — and is unambiguously distinct from sibling tools like marzban_users_update, marzban_users_get, and marzban_users_list. It also clarifies the tool's exact scope by not merely restating the title.

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 core purpose makes when-to-use obvious, but the description does not explicitly distinguish from alternatives or state when not to use it. It gives internal guidance around templateId and defaults, but no direct routing such as 'use update for existing users'.

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 indicate this is not read-only and not destructive, and the description adds useful behavioral context: the user's status is set to disabled, the access block is immediate, and the user record is retained. This goes beyond the annotations without contradicting them.

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 one clear sentence with no filler. It front-loads the core behavior and adds the important non-deletion caveat efficiently.

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 one-parameter mutation with an output schema and annotations, the description covers the essential effect and non-destructive nature. However, it omits any mention of reversibility, reactivation via the activate sibling, or what happens to existing sessions beyond saying access is blocked, leaving some contextual 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 single username parameter is indirectly linked by the description ('a user's status'), but no dedicated explanation is given for what the username refers to or how it is used. The schema has 0% description coverage, so the description provides only minimal compensation by indicating that the parameter identifies the affected user.

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 action ('Sets a user's status to disabled'), the target resource (the user), and the immediate effect (blocking access). It also clarifies that the operation is not deletion, which helps distinguish it from removing users, though it does not explicitly differentiate from sibling operations like hold or activate.

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?

There is no guidance about when to use this tool versus alternatives such as activate, hold, or create. The phrase 'immediately blocking their access' implies urgency or a need to revoke access, but no conditions, exclusions, or alternative tool recommendations are provided.

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 only say readOnlyHint=false and destructiveHint=false. The description adds meaningful behavior: it explains the fallback to 'now' when no expiration or already passed, and that expired/limited users are moved back to active. This goes beyond annotations and helps the agent anticipate 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?

Two dense sentences, no wasted words. The key nuance (relative addition, fallback to now, reactivation) is packed in early, and the alternative-handling sentence is a clear call-to-action.

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 mutating renewal tool with a true output schema, the description covers what happens to expiration, data limit, and status, and explicitly routes the agent away from the absolute-overwrite sibling. Nothing critical 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 description reinforces the schema's parameter docs by explaining addDuration is added to the current expiration, with fallback to now, and addData is added on top of the current limit. It also clarifies the relative rather than absolute nature. For username (the only undocumented param in schema), the description's 'renews a user' makes its role obvious.

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 ('Renews'), a resource ('a user'), and precisely what it does (adds duration and data). It names the sibling it is not (marzban_users_update) and contrasts relative vs absolute, so an agent can tell them apart.

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 instructs to use this instead of marzban_users_update for renewals, explaining the rationale (reads current expire/limit first so increment is relative). This gives clear selection criteria.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses valuable behavioral details: it returns computed summary data (data left, days left, usage percent) and handles the edge case where a user is effectively expired even before the status field catches up. This goes well beyond what annotations provide.

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 a single dense sentence, front-loaded with the core operation and followed by relevant computed-summary details. Every clause adds value and there is 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?

With only one parameter, an output schema present, and readOnly annotations, the description is sufficiently complete for a getter tool. It explains the single input, the summary output, and an important semantic edge case, leaving no critical gap for an agent to misuse the 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?

Schema description coverage is 0%, and the description only repeats the parameter name ('by username') without adding extra meaning such as exact-match behavior, case sensitivity, or how the username relates to the summary computation. The schema already provides constraints, but the description does little to compensate for the lack of parameter documentation.

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 ('Fetches') and a specific resource ('one user by username'), clearly distinguishing this tool from sibling tools like marzban_users_list that return multiple users. The mention of the computed summary further clarifies the tool's unique purpose.

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 clearly indicates this is for fetching a single user by username, which gives the agent a clear context for when to use this tool. However, it does not explicitly name alternatives or state when not to use this tool, so it falls just short of full explicit 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?

The description discloses the key behavioral trait: the user remains inactive until first connection, and only then does the on-hold timer start. This goes beyond the annotations, which only indicate non-read-only and non-destructive, by clarifying the actual state transition and timing semantics.

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 with no filler. The state change and behavior are front-loaded, and the use case is stated compactly in the second 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?

Given the output schema exists, return details are not required. The description covers what the tool does, when it is useful, and the key timing behavior. It might have also referenced the optional onHoldExpireDuration explicitly, but the overall context is sufficient for correct 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 schema documents onHoldExpireDuration in detail, and the description reinforces its meaning by explaining when the on-hold timer starts. However, the username parameter is not discussed in the description, and with only 50% schema coverage the description only partially compensates for the undocumented 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 uses a specific verb ('Sets a user's status to on_hold') and names the exact resource and state being changed. It also explains the distinctive lifecycle behavior — inactive until first connection, then the on-hold timer starts — which differentiates it from sibling tools like activate or deactivate.

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 clear usage context: 'Useful for provisioning an account ahead of time without starting its clock.' This tells the agent when this tool is appropriate, though it does not explicitly exclude alternatives or name 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?

The annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: pagination defaults (25), maximum page size (100), server-side search matching on username/note, and the recommendation to search instead of paging. This goes beyond what annotations alone communicate.

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 sentences, each earning its place: the operation and filters, pagination behavior and search preference, and the sibling alternative. The most important distinguishing information 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?

Given the output schema exists, the description does not need to explain return values. It covers the essential usage context: filters, pagination limits, efficient search usage, and when to choose marzban_users_get. No critical calling information 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 only 50%, with offset and status lacking meaningful documentation. The description partially compensates by mentioning the status filter and search behavior, and it repeats the limit default/maximum, but it does not clarify offset semantics or enumerate the status values.

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 ('Lists users') and immediately clarifies the filtering dimensions (status, search term). It also distinguishes itself from the sibling marzban_users_get by noting that the get tool should be used for a single known username.

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 explicit guidance on when to use this tool versus marzban_users_get, and it advises preferring 'search' over paging through all users. This is concrete, actionable routing information beyond the raw schema.

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 key behavior beyond the annotations is disclosed: partial update semantics — unspecified fields are left unchanged, not reset. The annotations only say readOnlyHint=false and destructiveHint=false, so this non-replace behavior is valuable. It stops short of discussing auth requirements or consequences, but the core behavioral trait is clearly covered.

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 compact sentences front-load the core behavior and then concisely point to the relevant sibling tools. There is no repetition of schema information and 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 complex 7-parameter update with nested objects and an output schema, the description covers the main decision points: partial update semantics and when to use alternative tools. It does not mention create as the opposite action, but the title and opening verb make that distinction clear; an output schema covers return values.

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 57%, and several parameters are already described in the schema (expire, proxies, inbounds, dataLimit). The description adds the general and important rule that omitting a field leaves it unchanged, which applies to all parameters, but it does not clarify otherwise undocumented fields such as note or dataLimitResetStrategy.

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 opens with a specific verb and resource: 'Partially updates a user' and explains the PATCH-like scope ('only fields you provide are changed'). It also names sibling tools for status and renewal, making it easy to distinguish from marzban_users_activate/deactivate/hold/extend.

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 explicit routing guidance: status changes should go to activate/deactivate/hold, and renewal should go to extend. This clearly states when not to use this tool and names the preferred alternatives, leaving no inference to the agent.

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 destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral context beyond the annotations: it discloses that the report includes per-node breakdowns and that the breakdown can be filtered by period, which helps the agent set expectations without needing to inspect output structure further.

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 tightly written sentences deliver all essential information with no filler. The main purpose is front-loaded, followed immediately by parameter usage guidance, and 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 read-only usage query with an output schema already present, the description covers everything needed to invoke it correctly: what is reported, which parameters affect the report, and what happens when the optional parameters are omitted. No critical behavioral or invocation details are 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 schema already documents start and end as optional ISO datetimes, covering 67% of parameters, and the description reinforces this with the specific rule 'omit both for all-time.' This adds semantic context about how the two time parameters interact, which is valuable beyond the individual schema descriptions. The username parameter is only constrained by schema pattern, but the description's focus on usage makes its role clear.

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 ('Reports') and names the resource ('data a user has used'), then enumerates exactly what is returned: total, lifetime total, current limit, and per-node breakdown. This makes the tool's purpose unmistakable and distinct from sibling tools like marzban_users_get or marzban_users_list, which focus on user configuration rather than traffic statistics.

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 clearly explains how to use the optional start/end parameters and explicitly states the all-time behavior when both are omitted. It does not name alternative sibling tools or specify when not to use this tool, but the usage context is evident from the description and the readOnly annotation, so the guidance is adequate.

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