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

Annotations already declare the operation read-only, idempotent, non-destructive, and open-world, so the description does not need to restate those. It adds no behavioral detail beyond what the annotations and basic return statement convey, but it does not contradict them either.

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 word contributes to defining the tool's return value.

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

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

For a no-parameter read-only tool with comprehensive annotations, the description is largely sufficient. The only gap is that 'account data' is not enumerated, and there is no output schema to clarify the return shape, but the identity mention provides reasonable context for an agent to invoke the tool correctly.

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

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

The tool has zero parameters, so there is no parameter meaning for the description to add. Per the rubric, the no-parameter case receives a baseline of 4.

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

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

The description uses a clear verb ('Return') and identifies the resource: sipgate account data plus the authenticated user's identity. 'Account data' is somewhat broad, but the identity clause makes the tool's purpose distinct from siblings like list_users and get_settings.

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 is given about when to use this tool versus alternatives such as list_users or get_settings. The intended use is implied by the description, but there are no explicit context signals, exclusions, or prerequisites.

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 communicate readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the result is paginated and that filters are optional, but it does not disclose ordering, response shape, rate limits, or authentication requirements. No contradiction with annotations.

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

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

A single sentence with the verb front-loaded, the core resource named, and the optional filters summarized. Every word earns its place; no redundant or vague filler.

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

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

For a simple read-only list operation, the description plus the detailed schema provide enough to select and invoke the tool correctly: required offset/limit are in the schema, optional filters are summarized, and annotations cover safety. The main missing context is the response shape and default behavior when no time range is provided, but that does not block correct invocation.

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

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

Schema description coverage is 57%, and the description adds value by grouping filters (direction, time-range, number, connection) that map to directions, from/to, phone_number, and connection_ids. However, it does not clarify limit, offset, or the directions enum values, so it only partially compensates for missing schema descriptions.

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

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

The description uses a specific verb and resource: 'List paginated call history', and enumerates the optional filter dimensions (direction, time-range, number, connection). This clearly identifies what the tool does and distinguishes it from siblings like send_sms, initiate_call, and list_users by its unique resource.

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 by the phrase 'List paginated call history', so an agent can infer this is the read-only history lookup tool. However, there is no explicit guidance about when to use it versus alternatives, nor any exclusions or routing to sibling tools.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description does not need to restate it. It adds useful context about the response scope, including that forwardings can be active or timeout, but does not disclose return format, pagination, or how the optional user_id affects the routing portion. This is modest added context, not a rich behavioral profile.

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

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

A single sentence front-loads the action ('Return') and packs the full scope into a compact list. There is no filler or repetition of annotation details.

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 is the primary source for return-value semantics, and it enumerates the main data categories: routing, phonelines, assigned numbers, and forwardings. It stops short of explaining terms like 'endpoint' or the exact behavior when user_id is omitted, but for a read-only retrieval tool with annotations covering safety, this is nearly complete.

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

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

The only parameter, user_id, is already fully documented in the schema with a clear description ('Limit phoneline forwarding details to one sipgate user ID'), so schema coverage is 100%. The tool description does not add further parameter semantics; the baseline 3 applies because the schema carries the burden.

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

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

The description uses the explicit verb 'Return' followed by a specific composite resource: number-to-endpoint routing, per-user phonelines, assigned numbers, and active/timeout forwardings. This content clearly distinguishes it from sibling tools like list_numbers, list_users, and set_number_routing, which cover narrower or mutating operations.

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

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

The description implies the tool is for retrieving routing and forwarding configuration, but it never states when to choose it over get_settings, list_numbers, or list_users, nor does it provide exclusions or conditions. The usage context is inferable but not explicit.

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 the tool read-only, idempotent, open-world, and non-destructive, so the description's 'Return' aligns with these. The description adds useful scoping about which settings are included, but does not disclose extra behaviors such as response variability or authorization requirements. With rich annotations, this is adequate but not exceptional.

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

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

One dense, well-structured sentence that front-loads the verb and lists the three distinct setting categories. Every phrase adds value, and there is no repetition of schema or annotation information. It is concise without omitting important scope.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers the key return categories and lets the agent decide whether it needs this data. The openWorldHint annotation partially accounts for an unspecified response shape, and the sibling list provides enough context to differentiate it. It could enumerate some concrete field names, but that is not essential for selection and invocation.

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

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

The single optional user_id parameter has 100% schema description coverage ('Limit settings to one sipgate user ID'), so the schema carries the parameter semantics. The tool description does not add parameter-specific detail, but none is needed given full schema coverage. A baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Return' and names a clear resource: user reachability settings, device availability/DND state, and voicemail settings. This distinguishes it from sibling tools like set_dnd (which mutates DND) and get_routing (which returns routing config). The scope is concrete and agent-actionable.

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

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

The description gives clear context on what settings are returned, so an agent can infer when to call this tool versus alternatives like set_dnd or list_devices. It does not explicitly state exclusions or name alternatives, but the specificity of the returned categories provides sufficient guidance for read-only settings lookups.

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, the description adds crucial behavioral detail: it may incur charges, it reads established calls before and after, returns the new session, and warns that ringing calls may not appear immediately. This goes well beyond the structured annotation fields and helps the agent anticipate side effects and timing.

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 sentence that front-loads the most important warning, states the core action, and then adds essential timing behavior. There is no redundant phrasing or filler, and every clause contributes actionable 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?

Given no output schema, the description still covers what happens before, during, and after the call: account changes, potential charges, the returned session, and the eventual visibility of ringing calls. Combined with the annotations, this provides a sufficiently complete mental model for correctly invoking the tool.

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

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

Schema description coverage is high at 75%, so the schema already documents most parameters. The description does not add additional meaning about caller, callee, caller_id, or device_id beyond what the schema provides. It stays at the baseline because it neither harms nor significantly enriches parameter understanding.

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, 'start a Click2Dial call', on a specific resource (the SIPGATE account), and explicitly warns that it changes the account. This clearly distinguishes it from read-only siblings like call_history and account_info, and from other communication tools like send_sms.

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

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

The description makes it clear the tool is for initiating a call, which implies its primary use case. However, it does not explicitly state when to use this tool over alternatives such as send_sms or set_forwarding, and it offers no exclusion criteria or conditional guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the default all-users behavior and the specific status fields returned. This exceeds a baseline score.

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

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

Two concise sentences with no wasted words. The primary action and resource are front-loaded, followed by the most important behavioral qualifier about scoping.

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

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

For a simple, read-only list operation with two optional parameters and no output schema, the description is complete. It states what the tool returns, how the optional user_id affects scope, and annotations cover safety and idempotency.

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 both parameters are already documented in the schema. The description adds meaningful semantics for user_id by explaining the default behavior when it is omitted, which goes beyond the schema's brief 'Limit results to one sipgate user ID'.

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

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

The description uses a specific verb ('List') and resource ('phones and devices'), and enumerates the meaningful attributes returned (owner, active routing, DND, online/register status). This clearly differentiates it from sibling tools like list_users and list_numbers, which target different resources.

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

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

The description gives clear context on scope: without user_id, all users are queried, implying that user_id narrows the result to one user. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds context about returning current endpoint assignments, but does not disclose return format, ordering, or pagination behavior beyond 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?

The description is one concise sentence that front-loads the primary action and resource, then adds the distinguishing endpoint-assignment detail. Every word contributes 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 simple read-only list operation with comprehensive annotations, required parameters documented in the schema, and no output schema required, this description is sufficient. It tells the agent exactly what the tool lists and provides enough context to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the limit and offset parameters are fully documented in the input schema. The description does not add parameter-level details, but it does not need to given the schema's completeness.

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

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

The description uses a specific verb 'List' with a clear resource, 'sipgate phone numbers', and adds the meaningful detail 'current endpoint assignments'. This clearly distinguishes it from sibling tools like list_users and list_devices.

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

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

The description makes clear this tool is for phone numbers and their endpoint assignments, so an agent can infer when to choose it over siblings. However, it does not explicitly state when not to use it or name alternative tools.

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

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

Annotations already communicate that this is a read-only, idempotent, non-destructive operation. The description adds the useful return-context detail that IDs are included for use by other tools, but it does not disclose pagination, ordering, or access requirements. This is adequate but not rich behavioral disclosure.

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, compact sentence that front-loads the core action and resource, then adds the one extra fact agents need (IDs for reuse). No words are wasted.

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

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

For a parameterless list tool with strong annotations, the description is complete. It names the resource, the scope, and the key output element (IDs), which is sufficient for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters, so the description has no parameter meanings to clarify. Baseline 4 is appropriate because no parameter documentation burden exists.

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 ('List'), a clear resource ('all users in the sipgate account'), and adds the useful detail that it returns IDs usable by other tools. This distinguishes it clearly from siblings like list_numbers and list_devices.

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

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

The description implies a usage context: use this tool when you need user IDs for other tools. However, it does not explicitly state when to choose this over account_info or other list tools, nor does it mention any 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?

The annotations already indicate destructive/read-only/idempotent hints, and the description adds material context beyond them: charges may be incurred, the account is changed, verification is required, and the returned history can update asynchronously. No contradiction with 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 tight sentences, front-loaded with the most decision-relevant warning about charges and state changes before the action. Every clause adds information and no schema details are 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 5-parameter destructive tool with no output schema, it covers prerequisites, side effects, costs, and the async return behavior. It could specify message/recipient expectations or failure semantics explicitly, but the schema plus warning make it reasonably complete.

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

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

With 60% schema coverage, the schema leaves message and recipient undocumented except for the recipient pattern. The description adds no per-parameter meaning beyond the generic 'send an SMS' and the SMS-capable extension hint, so it does not compensate for the gap.

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: 'send an SMS' on the SIPGATE account, with an added constraint 'after verifying an SMS-capable extension'. The action is unambiguous and naturally distinguished from siblings like initiate_call and set_dnd.

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

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

Provides clear context for when to invoke: send an SMS after verifying an SMS-capable extension. It also signals prerequisites and cost/state-change implications, but it does not name alternatives or explicit when-not-to-use scenarios.

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

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

Annotations already indicate mutability and destructiveness, but the description adds valuable behavioral context: it explicitly says the tool 'Reads and returns the device's before/after state,' which informs the agent about side effects and return behavior beyond the raw annotations.

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

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

The description is two sentences long, front-loads the core action, and includes the key behavioral detail about returning before/after state. Every sentence adds value with no redundant filler.

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

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

For a simple two-parameter tool with annotations covering safety and idempotency, the description is largely complete. It covers the operation scope and observable output. The only notable gap is lack of usage guidance relative to sibling tools, which is already penalized separately.

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 50%, but the description compensates by mapping 'enabled' to the enable/disable action, making the boolean parameter's meaning explicit. The schema also provides a helpful description for device_id ('Device ID returned by list_devices'), so both parameters are adequately semantically grounded.

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

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

The description uses a clear verb ('CHANGES') and specifies the exact resource and operation ('enable or disable Do Not Disturb for one device'). It distinguishes itself from sibling routing/forwarding tools by naming DND specifically, though 'THE SIPGATE ACCOUNT' is somewhat broad given the scope is a single device.

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 what the tool does but provides no guidance on when to use it versus alternatives like set_forwarding or set_number_routing. It does not mention any prerequisites, exclusions, or conditions that would help an agent decide between sibling tools.

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

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

Annotations already flag this as destructive and non-read-only, but the description adds valuable specifics: the operation replaces all forwardings, an empty array deletes all, and the tool reads and returns before/after state. This goes well beyond the structured hints and gives the agent a clear mental model of side effects.

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

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

Two sentences, no filler, and the core action is front-loaded. The empty-array deletion case and the before/after return behavior are both essential and included without extra words.

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

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

For a mutation tool with no output schema, the description covers the destructive scope, the deletion edge case, timeout routing, and the return value nature. Combined with fully documented parameters and relevant annotations, an agent has enough context to invoke the tool correctly.

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

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

Schema coverage is 100%, with each parameter already described in the input schema, so the description is not required to repeat parameter details. It reinforces the semantics of forwardings ('replacement list', '[] removes every forwarding') but does not add meaningful new meaning beyond the schema.

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

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

The description uses a specific verb ('replace') and a clear resource ('all forwardings for a phoneline'), and further clarifies scope with 'including timeout routing' and the empty-array deletion case. This makes it readily distinguishable from sibling tools like get_routing, set_dnd, and set_number_routing.

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

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

The description implies when to use the tool: whenever a complete replacement of forwardings is desired, and explicitly documents the deletion use case with an empty forwardings array. However, it does not name or contrast any sibling tool, so guidance about when not to use it or which alternative to choose is left to inference.

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

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

Annotations already signal readOnly=false and destructiveHint=true, and the description reinforces this with 'CHANGES THE SIPGATE ACCOUNT'. It adds useful behavioral detail beyond annotations by explaining that the tool reads and returns the number's before/after state, which is not present in the annotations or 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 two sentences with no filler. The most important intent ('CHANGES THE SIPGATE ACCOUNT') is front-loaded, then the action and return behavior are stated compactly.

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 full schema coverage, annotations covering safety, and a description that explains the mutation and return value, the definition is mostly complete. It could optionally mention that number_id comes from list_numbers, but the schema already covers that, so nothing critical is missing for this simple two-parameter 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%: both number_id and endpoint_id are already documented with meaningful descriptions. The tool description adds no additional parameter semantics, so the baseline score 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 states a specific action: route a phone number to a sipgate endpoint ID, and clearly identifies the affected resource. The explicit 'CHANGES THE SIPGATE ACCOUNT' framing distinguishes it from sibling get_routing, and the before/after state note clarifies what the tool does.

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

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

The description makes clear this is a mutation tool for setting routing, contrasting with the sibling get_routing. It provides clear context for when to use it, though it does not explicitly name alternatives or state when not to use it.

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