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

The description adds genuinely valuable context beyond the annotations: 15-minute expiry, per-user binding, and a server-side write-enable flag. However, it states that recommitting the same operation replays the first result via an idempotency key, which conflicts with the declared idempotentHint=false — an agent deciding whether a retry is safe gets two opposite signals. That said, the destructive nature of the call is at least consistent with destructiveHint=true, and the extra preconditions are real added value.

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?

Four compact clauses, front-loaded with the step indicator, with each sentence carrying a distinct actionable fact (protocol, expiry, authorization, server flag, idempotency). Nothing is redundant or padded.

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 destructive, open-world mutation with no output schema, the description covers the critical operational envelope: ordering, TTL, ownership, and server-side enablement. The remaining hole is the confirmation-hash contract and what a rejected commit looks like, so it falls just short of fully 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?

Schema coverage is only 50%: the nested "operation" parameter is documented as coming unchanged from telgea_prepare_change, but confirmOperationHash has no description anywhere. The description's "with its operationHash" hints at the pairing but never states that confirmOperationHash must equal the prepared operation's hash, which is the one parameter rule an agent most needs.

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?

"Step 2 of 2: send a prepared operation, unchanged, with its operationHash" names the exact action, the artifact it consumes, and its place in the two-step prepare/commit flow. An agent can immediately distinguish this from telgea_prepare_change without reading 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?

It gives concrete gating conditions: must follow preparation, valid for 15 minutes, only usable by the user who prepared it, and requires TELGEA_ENABLE_WRITES=true on the server. It doesn't explicitly name telgea_prepare_change as the prerequisite tool, though "Step 2 of 2" and the schema's parameter description make that inferable.

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 readOnly=false, idempotent=false, destructive=false and openWorld=true. The description adds the meaningful server-side write gate, which the agent could not infer from annotations, but says nothing about duplicate-name behavior, whether the new team is returned with an id, or side effects on supplied userIds.

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 with zero waste; the capability statement is front-loaded and the prerequisite follows. Nothing redundant is repeated from the name or schema.

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 non-idempotent mutation with no output schema, the definition covers the core action and the write-gating constraint, which is the most important operational fact. It stops short of what an agent needs to chain the call — notably whether a team identifier is returned — and leaves two of four parameters unexplained.

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 only 25% — only userIds carries a description. The description gestures at userIds ("optionally with members") but leaves emoji and costCode entirely undocumented in both schema and description, leaving half the call surface opaque for a write operation.

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 ("Create a team") and scopes it with "optionally with members." It is clearly distinguishable from telgea_update_team and telgea_list_teams by the creation verb, though it does not name those siblings 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?

Usage is implied by the create verb and the optional-members scope, and the TELGEA_ENABLE_WRITES=true prerequisite is a genuinely useful gating condition. However, there is no explicit steering toward or away from telgea_create_user, telgea_update_team, or guidance on when to add members at creation vs. later.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-redundant context: the server-side write gate TELGEA_ENABLE_WRITES=true and the boundary against plan provisioning. It stops short of saying what happens on a duplicate email or what identity is returned.

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, each carrying a distinct and necessary fact: the action, the sibling boundary, and the write prerequisite. Zero filler and the core purpose 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 non-idempotent write tool with no output schema and only 17% parameter coverage, the description covers the gating and scoping questions well but leaves the parameter contract and post-call behavior (duplicate handling, returned user identity) unexplained. Adequate, with clear 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?

Schema description coverage is only 17% — of six parameters only teamId carries any description. The description adds no meaning to email, firstName, lastName, costCode or employeeId, so the required-vs-optional semantics and the purpose of employeeId/costCode remain undocumented in both places.

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 ('Create a user (employee) in the organisation'), and explicitly delimits scope by stating it does not order a plan, naming the sibling (telgea_prepare_change kind=create_user_plan) that does. An agent can distinguish it from telgea_create_team and telgea_update_user without opening any 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?

It clearly routes the plan-ordering case to a named alternative and flags the server prerequisite TELGEA_ENABLE_WRITES=true, which tells the agent when the call is even possible. It does not explicitly state when to prefer telgea_update_user over creating a new user, so the guidance is strong but not exhaustive.

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 cover the safe read-only, idempotent, non-destructive profile. The description adds meaningful behavioral context by disclosing that eSIM activation codes and PIN/PUK are redacted and pointing to the credential-specific tool with a permission caveat.

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, with the lookup method front-loaded and the redaction/alternative note immediately after. No wasted language.

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 small lookup tool with no output schema and strong annotations, the description covers the key identifiers and the important redaction behavior. The remaining gap is the lack of guidance about requiring or prioritizing at least one identifier.

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%, so the description must carry parameter meaning. It does map the three inputs to email, E.164 phone number, and ICCID, but it does not clarify whether one identifier is required, how conflicts are resolved, or any precedence rules.

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 — finding one user's plan — and names the accepted lookup identifiers. It does not distinguish this from close siblings like telgea_get_user_plan or telgea_list_user_plans, so an agent must infer the boundary.

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 usage context by listing email, E.164 phone number, and ICCID as lookup keys, and it routes credential access to telgea_get_sim_credentials. However, it does not explain when to use this instead of telgea_get_user_plan or telgea_list_user_plans.

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 readOnly, idempotent and non-destructive, but the description adds behavior they cannot express: sensitive fields (eSIM activation codes, PIN/PUK) are deliberately redacted and access is permission-gated. This is exactly the kind of context an agent needs before assuming the response is incomplete. It stops short of describing error or not-found behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the payload summary first, the redaction caveat and alternate tool second. No filler and nothing important buried.

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?

There is no output schema, so the description carries the burden of describing the return shape, and it does so at a useful level of detail while flagging what will be missing. Complete enough to call correctly; only error/edge-case behavior is 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?

With 100% schema coverage on a single uuid parameter, the schema already documents numberId and points to telgea_list_lines / telgea_get_user_plan as sources. The description adds nothing about the identifier, so the baseline of 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 the resource ('One line') and enumerates what it returns: state, activation and termination-scheduled timestamps, and current/previous SIMs. That is enough to distinguish it from siblings like telgea_list_lines and telgea_get_line_connection. An explicit verb is absent, which keeps it just 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 routes the agent explicitly: if you need eSIM activation codes or PIN/PUK, use telgea_get_sim_credentials instead, gated on permission. That is a concrete alternative with a condition. It does not clarify when to prefer this over telgea_get_line_connection or telgea_list_lines, so the guidance is partial rather than exhaustive.

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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds value beyond that: "Live" signals real-time freshness rather than cached data, and the IMEI/IP handling rule (share only with the line's holder or IT) is a privacy constraint no annotation conveys.

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, zero filler. The return payload leads, the usage scenario follows, and the data-handling caveat closes — each clause earns its place and nothing is repeated from structured fields.

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 no output schema, the description compensates by enumerating the returned fields, and it covers the single parameter via the schema plus a privacy rule. Minor gaps remain: no note on behavior when a line is inactive or suspended, and no indication of whether results are cached.

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 is one required parameter and schema coverage is 100%, with the schema documenting it as "Line id." with UUID format and pattern. The description never mentions numberId, so it adds nothing beyond the schema; baseline 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?

States a specific resource and scope: "Live network status of a line," then enumerates exactly what comes back (attached state, last seen, serving network, 2G–5G, APN, IMEI). The word "live" implicitly separates it from the static metadata tool telgea_get_line, but no sibling is named explicitly, so it stops 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?

Gives a concrete triggering scenario ("my phone has no signal" support), which is a real routing signal an agent can match against a user complaint. It provides no when-not conditions and does not point to alternatives such as telgea_get_line or telgea_get_sim_credentials for related data.

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 annotations (readOnly, idempotent, openWorld), the description discloses the return semantics: a state machine progression CREATED → SUBMITTED → ACCEPTED → SUCCEEDED with failure branches carrying a reason. That return-value context is genuinely additive. It stops short of noting auth requirements or behavior for unknown/invalid ids.

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 compact sentence, front-loaded with the resource and immediately followed by the state lifecycle. No filler, though the telegraphic fragment style sacrifices a little readability.

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 no output schema, the description must carry return-value burden, and it does reasonably well by naming the possible statuses and that rejections include a reason. It leaves minor gaps (other returned fields, error behavior for bad ids), but an agent can call 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?

There is only one parameter (portInId) and schema description coverage is 100%, with format and pattern already in the schema. The description adds no syntax or semantics about the id, 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?

States a specific verb and resource ('Status of one port-in') and enumerates the lifecycle states, so an agent knows this is a single-record status read rather than a listing. It does not explicitly contrast with siblings like telgea_list_port_ins_for_line or telgea_get_port_in_requirements, which keeps it from 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?

No guidance on when to use this versus alternatives. The agent must infer that list_port_ins_for_line is for enumeration and get_port_in_requirements/validate_port_in are prerequisites, since the description never mentions them or any preconditions.

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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context by explaining that the result can be returned either as a field list or as a JSON Schema, which is especially valuable 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?

The description is a single front-loaded sentence with no filler. Every phrase contributes either the resource, the country scoping, or the output format choice.

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 two-parameter lookup tool with no output schema, the description provides enough context to understand what is returned and how the format parameter changes the response. The schema covers the parameter constraints, and the annotations cover safety, leaving only minor details such as country coverage unstated.

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%, so the description must carry parameter meaning. It does map both parameters semantically: 'for a country' corresponds to countryCode, and 'as a field list or a JSON Schema' corresponds to the format enum. It does not explain the two-letter country code pattern, the default format, or required status, so compensation is partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource as the fields required for a number port-in by country, and it notes the two output representations. It is specific enough to distinguish this from general port-in retrieval or validation, though it does not explicitly name those sibling 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 intended use is implied: fetch port-in requirements for a country. However, there is no explicit guidance on when to use this versus telgea_validate_port_in or telgea_get_port_in, and no prerequisites or exclusions are stated.

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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value: the server-flag gate and the warning that anyone holding the activation code can install the line. It stops short of describing what happens when the flag is off (error vs. empty) or whether PIN/PUK can be absent for some line types.

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, zero filler, and the return value is front-loaded before the precondition and the warning. Each sentence carries a distinct fact (what it returns, what it needs, how to handle the output).

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 an annotated read tool with no output schema, this is complete: the returned payload is enumerated in the description (LPA string, QR content, PIN/PUK), the server prerequisite is stated, and the security caveat is given. Nothing an agent needs in order to call it safely 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% and both parameters are documented in-schema (numberId as 'Line id.', reason as audit-log rationale). The phrase 'for one line' reinforces the idempotent single-target nature of numberId but adds no new syntax or 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?

The description names the exact resources returned (eSIM activation code / LPA string / QR content and PIN/PUK) and scopes them to 'one line'. No sibling in the list returns SIM secrets, so the agent can route to this tool unambiguously without opening the 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?

It states a hard precondition (TELGEA_ENABLE_SIM_SECRETS=true on the server) and a handling rule ('Give it only to the line's holder'), which is exactly the context an agent needs before calling. It does not name an alternative or a when-not-to-call condition, which keeps it short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the aggregation semantics: it returns highest/lowest/average alongside per-day/per-month buckets, and it signals cost-efficiency. That is meaningful context beyond the annotations, though return shape and pagination are not addressed.

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, front-loaded with what is returned, then filters, then the cost/value pitch. No filler; every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries the burden of explaining returns; it partially does so via highest/lowest/average but not the record shape. For a 7-parameter analytics tool with 29% schema coverage and a near-twin sibling, the definition leaves notable gaps in date semantics and sibling differentiation.

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 only 29%, so the description must compensate. It does explain three filter dimensions (user, number, serving country) and the day/month interval, but says nothing about startDate/endDate semantics or what orderBy sorts by — leaving roughly half the parameters uninterpreted in both places.

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+resource with real substance: aggregated data/voice/SMS consumption per day or month, including highest/lowest/average. This clearly separates it from raw listing conceptually, but the description never names sibling telgea_list_usage, which is the obvious point of confusion.

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

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

"Cheapest way to answer 'how much did we use'" implies the usage context (aggregate consumption questions) but gives no explicit when-not or alternative. An agent choosing between this and telgea_list_usage gets no routing 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds return-shape context (current spend, paused flag) and the word 'effective', hinting the value may be derived rather than the raw configured threshold — but it never explains that distinction, nor error behavior for an unknown userId.

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 efficient sentence with no filler, though it leads with a noun phrase ('A user's effective cost threshold...') rather than a verb, making the action slightly less front-loaded than ideal.

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 no output schema, the description does list what is returned (threshold, current spend, paused status), which is useful. But it omits what 'effective' means versus configured, whether paused reflects line suspension, and how a missing user/usage type behaves — gaps that matter for a lookup 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 100%, including the enum and the clarifying note that VOICE means international calling, so the schema does the heavy lifting. The description only restates the usage-type categories (DATA, VOICE, SMS/MMS) without adding anything the schema doesn't already say.

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 names the resource (a user's effective cost threshold, broken down by DATA/VOICE/SMS/MMS) plus the companion fields (current spend, paused status). It distinguishes itself implicitly from list_cost_thresholds and set_cost_threshold by being a per-user, per-usage-type lookup, though it never explicitly frames itself as 'get X for one user/usage type' against those 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?

No guidance on when to use this versus list_cost_thresholds or get_user_plan, and no note on when cost threshold data is meaningful (e.g., before calling set_cost_threshold). The agent must infer the use case entirely from the sibling names.

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 this as a read-only, idempotent, non-destructive, open-world operation. The description adds valuable non-annotated context by disclosing that eSIM activation codes and PIN/PUK are redacted, and by pointing to the alternative tool for privileged access. It does not, however, describe error behavior or precise authorization conditions.

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. The core return contents are front-loaded, followed by the redaction caveat and the alternative tool. 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?

With no output schema and annotations covering the safety profile, the description does well by listing the key returned fields and the redaction behavior. It is nearly complete for a single-parameter read tool, though it omits what happens on invalid or unknown userId.

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 explains that userId addresses the plan by its user. The description adds no further parameter meaning, so the baseline of 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 clearly states the resource and scope: a full plan for a user, including status, local/travel numbers, line state, and SIM ICCID. It distinguishes itself from telgea_get_sim_credentials by noting redaction, but does not distinguish itself from closely related siblings like telgea_list_user_plans or telgea_find_user_plan.

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 one explicit routing rule: use telgea_get_sim_credentials if you are allowed to see redacted eSIM codes and PIN/PUK. However, it provides no guidance on when to use this tool versus telgea_list_user_plans or telgea_find_user_plan, which is a notable gap given the sibling list.

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 this as a read-only, idempotent, non-destructive, open-world operation. The description adds useful semantic context by defining thresholds as monthly spend caps and clarifying the three possible scopes, but it does not describe return shape, pagination, or other behavioral details beyond what the 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?

The description is a single, front-loaded sentence fragment with no wasted words. It communicates the resource and scope 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 list-style tool with full schema coverage and rich annotations, the description supplies enough context to understand that it concerns monthly spend caps at organisation, team, or user scope. It does not mention that results are returned as a list or describe pagination, but no output schema exists and the annotations already cover the safety 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?

Schema description coverage is 100%, so the schema already documents teamId, userId, and usageType in detail, including the omission rule for organisation-level thresholds and the VOICE meaning. The description reinforces the scope model but does not add parameter-level information beyond what the schema provides; baseline 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 identifies the specific resource (cost thresholds), explains that they are monthly spend caps, and names the three possible scopes: organisation, team, or user. It is clear what the tool is about, but the explicit listing action comes from the tool name rather than the description, and it does not distinguish itself from the sibling get/set/remove cost threshold tools.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives such as telgea_get_user_cost_threshold or telgea_set_cost_threshold. The usage is only implicitly suggested by the resource name and scope, leaving the agent to infer the correct selection context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description usefully adds that each member's data use is returned, but it does not disclose pagination, ordering, or whether all members are always returned.

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 terse fragment with no wasted words, but the absence of a verb and complete sentence structure makes it less front-loaded and clear than it could be.

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 read-only list, the annotations and schema carry most of the burden. Still, the description omits whether results are paginated, ordered, or otherwise scoped, which would help an agent 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?

There is only one parameter, poolId, and schema coverage is 100% with a UUID format and description. The description adds no parameter-level meaning, but the schema fully documents the sole parameter, so the baseline of 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 fragment names the resource (data pool members) and adds that each member's data use is included, which goes slightly beyond restating the name. However, it lacks a clear verb and does not explicitly differentiate this from sibling list tools such as telgea_list_data_pools.

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 on when to use this tool versus alternatives like telgea_list_data_pools or other list tools. No prerequisites, exclusions, or usage context 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 already declare readOnly=true, idempotent=true, destructive=false, and openWorld=true, so the safety profile is covered. The description adds value by disclosing what the response surfaces (region, GB totals/consumed/remaining, expiry, active restrictions), but it says nothing about scope (all pools across teams or just the caller's) or whether results are paginated.

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 compact clause with zero filler, front-loading the resource and its field set. It is slightly under-specified rather than over-long, but no sentence is wasteful.

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 no output schema, the description correctly takes on the burden of describing return values and does so reasonably. However, it omits the listing scope and any result-set behavior, leaving gaps an agent would want filled for a read-only enumeration 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 tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate and the empty schema is self-explanatory.

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 resource (shared data pools) and enumerates the attributes exposed, but it is a noun-phrase fragment with no verb and does not distinguish this from the sibling telgea_list_data_pool_members, which an agent could easily confuse it 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?

There is no statement of when to call this versus alternatives, no prerequisites, and no mention of the obvious sibling telgea_list_data_pool_members. The agent must infer usage purely from the tool name.

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 establish read-only, idempotent, non-destructive behavior. The description adds important non-obvious behavior: sensitive fields are redacted, an alternative tool exists for authorized credential access, and state filtering has a higher cost. These are meaningful additions 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 four sentences are front-loaded and each carries useful information: returned fields, filters, redaction/alternative path, and state-filter cost. There is no filler 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 read-only list tool with no output schema, the description gives the key returned fields, filter surface, redaction behavior and cost caveat. Pagination and ordering are left to the schema descriptions, which is acceptable but leaves some operational detail outside the description.

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 40%, and the description compensates by naming the five main filters (msisdn, iccid, userId, type, state) plus the type values local/travel and the state filter cost. However, it does not explain page, maxPages, pageSize, orderBy or orderDirection, leaving half of the parameters without description-level semantics despite the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource (list lines/numbers) and enumerates what is returned, including type, state, ICCID and holder. It also distinguishes the credential-viewing path by naming telgea_get_sim_credentials for redacted eSIM/PIN/PUK data, so an agent can tell what this tool covers versus a related one.

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 clearly routes credential access to telgea_get_sim_credentials when the caller is allowed, and it warns that filtering by state is costlier than other filters. It does not explicitly contrast with telgea_get_line for single-line retrieval, but the list-versus-get distinction is strongly implied.

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 establish read-only, idempotent, non-destructive, and open-world behavior, so the description has a lower bar. It adds the useful nuance that the result covers all attempts, but it does not mention pagination limits, daily budget impact, ordering, or what constitutes an 'attempt' beyond the schema’s parameter notes.

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?

It is a single, front-loaded sentence with no redundant or wasted text. The scope constraint is stated 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 read-only listing tool with fully described parameters and safety annotations, the description identifies the return subject ('all port-in attempts') and scope ('for one line'). It does not need to repeat pagination details from the schema, though adding return-order or result-shape context would improve it further without an output schema.

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 every parameter is already documented in the schema, including pagination and budget semantics. The description adds no parameter-level meaning beyond identifying that a line is required, so baseline 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 resource (port-in attempts) and scope (for one line), so an agent can tell it is a line-scoped listing operation. It does not explicitly differentiate itself from the sibling `telgea_get_port_in`, but the plural 'all port-in attempts' implies a list rather than a single fetch.

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 phrase 'for one line' implies usage when an agent needs all port-in attempts tied to a known line, but there is no explicit guidance on when to use this versus `telgea_get_port_in` or other port-in tools. No exclusions, prerequisites, or alternatives are named.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds useful domain context — these are retail pay-as-you-go prices resolved per destination country — but says nothing about whether historical rates are retrievable, currency/units of the returned prices, or result size. Modest value on top of 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 tight sentence with the key qualifier ('pay-as-you-go retail') front-loaded and no filler. It is efficient, though the terseness edges toward under-specification for a five-parameter tool.

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 no output schema, the description should convey what a 'rate' record looks like (price, currency, unit, destination) and how asOfDate/direction shape the result; it conveys none of that. Annotations cover safety, but an agent still cannot predict the response shape or the meaning of three of five parameters from this definition.

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 only 40%, so the description has to compensate, and it partly does: it expands the `type` enum into words and reinforces `market` as the home market. However, `asOfDate`, `direction`, and `servingCountry` are never explained in the description, and 'per destination country' is ambiguous since no destination parameter exists — the closest is servingCountry, which the schema labels as the roaming location.

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 (pay-as-you-go retail rates), its scope (home market), and the variants covered (international voice/SMS/MMS, roaming data, per destination country). It is a noun phrase with no explicit verb, but combined with the 'List Rates' title an agent can tell this is a rate-lookup tool rather than a usage or line tool. No sibling is directly overlapping, so no differentiation is needed.

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 statement of when to use this tool versus the many other listing tools (list_usage, list_user_plans, search_capabilities), nor any prerequisite or exclusion. Usage is only inferable from the resource name. An agent must guess whether this is for pricing lookups before ordering plans or for explaining charges.

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 readOnly, idempotent, non-destructive and open-world, so the safety profile needs no restating. The description does add one piece of real value beyond annotations — that results include member counts and cost codes — but says nothing about page budget consumption, whether all teams or only visible ones are returned, or ordering.

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 front-loaded sentence with zero filler; the resource, its domain meaning, and the payload contents all land in one read.

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 no output schema, the description usefully previews the return payload (member counts, cost codes), and the pagination semantics are fully carried by the schema. The remaining gap is context about scope — whether the list is tenant-wide or filtered to the caller's permissions — which matters for an open-world read 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 100% with three well-documented optional pagination parameters (page/nextPage continuation, maxPages against the daily budget, pageSize max 50). The description adds no parameter meaning of its own, 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?

Specific verb+resource ('List teams') with a parenthetical clarifying what a team is ('billing/access groups') and what the rows carry ('member counts and cost codes'). It implicitly separates itself from telgea_create_team / telgea_update_team and from telgea_list_users by naming the resource distinctly, though it never names a sibling 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?

There is no when-to-use or when-not-to-use guidance: nothing tells the agent to prefer this over telgea_list_users or telgea_list_data_pool_members, or to call it before telgea_create_team to check existing teams. Usage is only inferable from the tool name.

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 read-only/idempotent/non-destructive, yet the description adds non-obvious behavior: each call consumes requests from a 1000/day budget shared across everyone using the key, results are cursor-paged, and records expose who called whom (a privacy-relevant detail). This is the kind of cost and data-sensitivity context annotations cannot express.

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 dense sentences: what is returned first, then window/paging mechanics, then budget cost, then alternative routing. No filler, and the most decision-relevant facts (detail-only usage, request budget) 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?

With no output schema, the description compensates by enumerating the record fields an agent will receive. Combined with the budget, window and paging notes, there is nothing essential missing for calling this 6-parameter list 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 coverage is high (83%, only pageSize undocumented), so the schema carries most parameter meaning. The description still adds framing beyond it by calling out the 31-day window cap and that paging is cursor-based rather than offset-based, telling the agent to iterate with nextCursor instead of requesting everything at once.

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 verb+resource (raw call, SMS, MMS and data records) and enumerates the record contents (timestamps, amount, roaming/international class, counterparty), so an agent knows exactly what it returns. It also explicitly distinguishes itself from the sibling aggregator by stating that totals belong to telgea_get_usage_analytics.

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 an explicit routing rule: use telgea_get_usage_analytics for totals, and reach for raw records 'only when the detail is needed' — a clear when-to-use/when-not paired with a named alternative. It also surfaces the operational constraint (max 31-day window, cursor paging) that shapes how to call 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?

Annotations already declare readOnlyHint/idempotentHint, so the safety profile is covered; the description adds genuinely new context by disclosing the 1000/day shared request budget each call consumes. It stops short of noting that maxPages multiplies that cost, leaving part of the rate-limit story in the 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 tightly packed sentences, front-loaded with what the tool returns, followed by the cost caveat. Minor sloppiness in the trailing ellipsis inside the status list, but no wasted sentences.

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 no output schema, the description usefully names the returned fields, and the cost disclosure covers the main behavioral risk for a read-only list. Pagination mechanics are left to the schema, which documents them adequately, so only small gaps remain.

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 60%, and orderBy/orderDirection lack descriptions entirely; the word 'Sortable' hints at their existence but does not map to them or explain defaults. The description adds little param meaning beyond field enumeration, consistent with a baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List subscriptions (user plans)') and enumerates the fields returned (user, status, local number, team), so the agent knows exactly what comes back. It does not differentiate itself from siblings like telgea_find_user_plan or telgea_get_user_plan, 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?

'List' plus 'Sortable' implies bulk enumeration over single-record lookup, but the description never says when to use this instead of find_user_plan/get_user_plan or names any alternative. Usage is inferred rather than stated.

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 readOnly/idempotent/non-destructive, so the description's real contribution is the quota disclosure: 'Each call spends Telgea requests from the 1000/day budget shared by everyone using the key.' That is genuinely useful behavioral context an agent can't get from structured fields. It stops short of 5 only because it doesn't quantify cost per page beyond what the schema hints.

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: the first covers scope and returned fields, the second covers filtering, and the third covers quota cost. No filler, and the most decision-relevant information is up front.

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 no output schema, the description compensates by enumerating the returned fields, and it discloses the shared daily budget, which matters for a paginated tool. The main residual gap is pagination behavior (how to continue via nextPage), though the schema's page parameter covers most of that.

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 parameters are self-documenting (page, pageSize, maxPages each explain their budget cost). The description adds the exact-match semantics for email/employeeId, but that is largely a restatement of the schema's 'Exact email.' 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 gives a specific verb ('List') and resource ('organisation's users (employees)') and enumerates the returned fields (name, email, team, employee id, cost code), so the agent knows exactly what comes back. It doesn't explicitly name the sibling read tools (list_user_plans, list_teams) to differentiate, which keeps it just 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?

The description states that filtering is by exact email or exact employeeId, which implies the lookup use case, but it never says when to prefer this over siblings like telgea_list_teams or telgea_find_user_plan, nor any prerequisites. Usage is implied rather than spelled out.

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 flag it as a non-read-only, non-destructive, non-idempotent open-world call; the description adds the critical facts an agent could not infer: no side effect is transmitted until commit, the return is a *signed* preview, a server-side env flag must be enabled, and human confirmation is required. This is exactly the behavioral context annotations cannot carry.

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 dense sentences, front-loaded with the gating condition, and no filler. The opening clause ('Step 1 of 2 for what costs money or cannot be undone') is slightly telegraphic in grammar but still parses correctly and earns its brevity.

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?

Covers staging, side-effect posture, prerequisite flag, and the human-in-the-loop requirement, which is strong for a 12-parameter, no-output-schema tool. It omits how the signed preview is carried into telgea_commit_prepared_operation (a token/handle returned by the preview), which the agent needs to close the loop.

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 92%, so per-parameter meaning is already documented for kind, userId, numberId, portInId, countryCode, terminationDate, deleteUser, etc. The description only restates the enum of kinds (identical to the schema enum) and adds no guidance on the conditional field requirements or the `fields` object. Baseline 3 is correct.

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 ('prepare' a change), enumerates the exact eight operation kinds it covers, and declares it is 'Step 1 of 2' which pairs it with telgea_commit_prepared_operation. An agent can tell immediately this is the preview stage, not the executor.

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 trigger ('what costs money or cannot be undone'), explicit staging rule ('Step 1 of 2', 'nothing is sent'), explicit prerequisite ('Requires TELGEA_ENABLE_WRITES=true'), and explicit workflow instruction ('Show the preview and warnings to the user and get an explicit yes before committing'). Routing to the sibling commit tool is unambiguous.

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 signal a non-read-only, non-destructive mutation, and the description adds two things they don't: the side effect of releasing paused usage and the server-side write-enablement requirement. It stops short of stating idempotency or behavior when the threshold is absent, but the added context is genuinely 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, zero filler: the action and its effect come first, then the operational prerequisite. Nothing is repeated from the schema or annotations.

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 3-parameter mutation with full schema coverage and annotations, the description supplies the effect and the write-gate precondition, which is what an agent most needs. It is only slightly thin on the no-threshold edge case and on pointing back to the sibling setter.

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 the teamId/userId omission semantics and the VOICE enum meaning already documented in the schema. The description adds no parameter information at all, 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?

"Remove a spend cap" is a specific verb+resource that clearly distinguishes this from telgea_set_cost_threshold and telgea_list_cost_thresholds by name alone. The added clause "releasing paused usage" clarifies the effect, though it doesn't explicitly contrast with the setter sibling.

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?

Usage is only implied by the name and the stated precondition (TELGEA_ENABLE_WRITES=true). There is no explicit when-to-use vs. telgea_set_cost_threshold guidance, nor what happens if no threshold is currently set.

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 readOnly/idempotent/non-destructive/openWorld, and the description adds the important behavioral fact that no Telgea operation is actually executed. What is missing is any hint of the return shape (tool names, descriptions, ranking) — notable given 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 terse clauses with the core distinction ('does not call Telgea') front-loaded; no filler. It verges on under-specification rather than bloat, but 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 schema-less-output discovery tool, the definition should explain what results look like and how to consume them; it doesn't. Annotations cover the safety profile, but the parameter documentation gap and undisclosed return format leave real holes for a tool whose output is the whole point.

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 0% and neither parameter is mentioned in the description. An agent must infer that 'query' is the search term and 'limit' caps results, with no guidance on syntax, match fields, or default behavior. With zero structured documentation, the description should have compensated but does not.

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 ('Find the Telgea tool to use') and clarifies the resource is a meta/discovery layer rather than a Telgea operation. It distinguishes itself from the many action siblings via 'Does not call Telgea. Discovery only.' Minor gap: it doesn't state what a match looks like, but the routing intent is 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?

'Find the Telgea tool to use' implies the use case (resolve an intent to a concrete tool) but never states when-not-to-use or how to choose among results. The 'Discovery only' note implicitly contrasts with siblings that do call Telgea, but no alternatives are named and no post-discovery guidance is given.

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?

Goes beyond the annotations by disclosing that the call does not hit the Telgea API and by naming the two facts returned (tiers, budget usage) — material for an agent deciding whether it is safe/cheap to call. Annotations already cover read-only, idempotent and non-destructive, so the remaining burden is light. Minor tension: openWorldHint=true suggests external interaction while the description emphasizes no external call.

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 what it returns, followed by the key constraint and the scope label. Nothing redundant; every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only status tool the description is nearly sufficient, and it compensates for the absent output schema by naming the returned facts. It stops short of describing the response shape (e.g. how tiers or budget usage are formatted), which is the only 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?

The tool takes no parameters, so per the baseline this scores 4. There is nothing for the description to disambiguate at the input level, and it correctly signals a parameterless invocation.

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: shows enabled tiers and daily request budget consumption for this instance. The 'Does not call Telgea' clause cleanly separates it from every sibling tool, all of which are Telgea API operations on users, lines, plans, etc. An agent can identify it as the instance-level discovery tool without opening anything else.

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?

'Discovery only' and 'Does not call Telgea' imply a usage context (cheap pre-flight check of capabilities/quota), but there is no explicit 'use this when' or 'use X instead' routing. The agent must infer that this is the right first call before invoking budget-consuming 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 only declare the generic profile (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description goes well beyond with the actual side effect of hitting the cap, the server-side write flag required to execute, and the delayed-effective-date behavior disclosed via the appliesFromNextMonth result field. That is exactly the auth/precondition/aftermath context the annotations cannot express.

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 action and scope, then enforcement consequence, then prerequisite and timing caveat. No sentence is redundant and nothing is buried.

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?

There is no output schema, and the description compensates by naming the one result field an agent must check (appliesFromNextMonth). For a mutation tool it covers consequences, prerequisites, and timing; it could still state whether re-setting overwrites an existing threshold and whether a threshold identifier is returned.

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 documents teamId/userId omission semantics, maxAmount currency basis, and the VOICE enum meaning. The description's mention of scope targets and usage types largely restates that, adding no format or constraint detail beyond the schema — 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?

States a specific verb and resource ("Set a monthly spend cap") and names the exact scope options (organisation, team, user) plus the covered usage types. This clearly distinguishes it from read-side siblings like telgea_list_cost_thresholds, telgea_get_user_cost_threshold, and the destructive telgea_remove_cost_threshold.

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 the operational consequence ("Reaching it pauses that usage") and the hard prerequisite (TELGEA_ENABLE_WRITES=true), which tells the agent when the call will fail. It stops short of explicitly routing to siblings — e.g. to inspect existing caps before setting, use telgea_list_cost_thresholds, or to undo, use telgea_remove_cost_threshold.

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?

Adds real context beyond the annotations: the blast radius is limited to data because calls and SMS keep working, there is a server-side write gate (TELGEA_ENABLE_WRITES=true), and the reason string lands in an audit log. The annotations already declare destructiveHint/openWorldHint, so what remains unexplained is whether restore fully reverses a restrict and what a partial failure looks like.

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?

Four short sentences, front-loaded with the action and scope, then side effects, then the prerequisite gate, then the safety instruction. Nothing is repeated and nothing is padding.

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 destructive, non-idempotent mutation with no output schema, it covers scope, side effects, prerequisites, and the confirmation requirement. It leaves gaps on mutual exclusivity of the two identifiers and on what a successful response confirms, which matters for a write the agent must report back to the user.

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 75%, so the baseline applies. The description restates the userId/numberId scoping that the schema descriptions already carry ("Every line of this user." / "One line.") and never says whether the two are mutually exclusive or what happens if both are sent.

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 pair (stop/restore) and resource (mobile data), and pins the two scoping targets to their parameter names (numberId = one line, userId = every line). It does not distinguish itself from the sibling telgea_set_line_suspension, which an agent could easily confuse with a data restriction, so it falls short of full sibling differentiation.

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 operating context: writes must be enabled server-side and the agent should confirm with the user before acting. It never says when to choose this over telgea_set_line_suspension or how to pick numberId vs userId when both are available, so exclusions and alternatives are missing.

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?

Goes beyond the destructive/openWorld/idempotent annotations by explaining the real-world consequence: the holder is cut off from calls, SMS and data completely until restored. The writes-flag requirement and confirmation rule are useful extra context an agent cannot infer from 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?

Three tight sentences: purpose first, then prerequisite and consequence, then the confirmation requirement. Every sentence carries operational weight and nothing is repeated.

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 destructive mutation with no output schema, the description covers the key things an agent needs: what it does, the server gate, the scope of impact, and the user-confirmation step. Only minor gaps remain, such as what a restore actually re-enables.

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 only 67%, and the description adds no meaning for any parameter: it never explains numberId, the suspend/restore enum, or the reason field's audit-log purpose (that lives only in the schema). The description relies entirely on the schema for parameter semantics, leaving the coverage gap unfilled.

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 pair of verbs (suspend/restore) on a specific resource (a line), with a concrete example of when suspension applies (a lost phone). No sibling tool does this, so the agent can route to it immediately.

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 (lost phone) and a hard prerequisite (TELGEA_ENABLE_WRITES=true) plus an operational rule (confirm with the user first). It does not name alternatives or carve out when-not-to-use cases, which keeps it below a 5.

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

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

Annotations only mark this as a non-read-only write, so the description carries the burden and delivers: the write-gate requirement and the full-replacement semantics of userIds are both behavioral facts not encoded in structured fields. It does not clarify partial-update semantics for the remaining fields (whether omitted name/emoji/costCode are preserved or cleared), which matters for a non-idempotent mutation.

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 padding, with the operation set front-loaded and the operational prerequisite and destructive-replacement caveat trailing in descending priority. Every clause carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and a 5-parameter mutation, the description should tell an agent how to call it safely; the write gate and replacement semantics do that. The only gap is unstated behavior for partially specified updates, which is meaningful but not fatal given no output schema exists to explain returns.

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 40% (only teamId and userIds are annotated), but the description compensates by naming all four optional fields and explicitly spelling out userIds as a wholesale replacement. Baseline for low coverage would be higher, but the description adds no format or constraint detail for name, emoji, or costCode beyond their names.

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 ("Rename a team, change its cost code/emoji, or replace its member list") and enumerates every mutable field, so an agent immediately knows what the tool touches. It never names a sibling, but the "team" resource is enough to separate it from telgea_update_user and telgea_create_team.

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?

"Requires TELGEA_ENABLE_WRITES=true on the server" is an explicit precondition an agent must check before calling, and "userIds replaces the whole member list" warns about the dangerous mode of use. It stops short of naming alternatives or stating when not to use it (e.g., use telgea_create_team for new teams).

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=false, idempotentHint=false and destructiveHint=false, so the safety profile is carried by structured data; the description adds the non-obvious server-side write gate, which is real value. However, it omits key behavior for a mutation: whether omitted fields are left unchanged, what happens on an unknown userId, and why the operation is non-idempotent.

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, front-loaded with the mutable field list and followed by the prerequisite. No filler and nothing buried.

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 7-parameter mutation with no output schema and low schema description coverage, the description covers the field set and the write-enable prerequisite but leaves the partial-update contract and error behavior unstated. Adequate to attempt a call, not complete enough to call confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 29% across 7 parameters, so the description must compensate — and it partly does by enumerating the mutable fields (name, email, team, cost code, employee id), which maps onto firstName/lastName, email, teamId, costCode and employeeId. It never mentions that userId is required or that these are optional partial-update fields, so the mapping to the schema still requires inference.

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 ('Change') and resource ('a user') and enumerates the mutable fields, so an agent immediately knows this is a partial user update. It implicitly distinguishes itself from telgea_create_user and telgea_update_team by naming the target resource and its fields, though it does not explicitly name those 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 only usage guidance is the prerequisite 'Requires TELGEA_ENABLE_WRITES=true on the server', which is genuinely useful operational context. There is no statement of when to prefer this over telgea_create_user or how it relates to other mutating tools, and no 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context that this is a dry-run validation and explicitly does not submit anything, though it repeats the point and says nothing about the validation result format.

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 short and front-loads the validation-only nature of the tool. However, 'without submitting anything' and 'Does not submit' are redundant, costing a sentence without adding new meaning.

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 five-parameter nested validation tool with no output schema, the description covers the core dry-run behavior and submission alternative. It leaves gaps around what a validation result looks like and any prerequisites such as fetching requirements first, though the schema hints at those dependencies.

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 40%, and the description adds no information about the five required parameters. It does not explain countryCode, msisdn, executionDate, or how the nested fields object should be populated beyond what the schema already partially documents.

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: checking port-in data against Telgea rules without submitting. It clearly distinguishes this validation tool from the submission path by naming telgea_prepare_change kind=submit_port_in.

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 says when to use this tool (to validate without submitting) and where submission should go instead. The alternative path is named directly, leaving little ambiguity for an agent choosing between validation and submission.

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