Placetel MCP by usefulapi

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

Adds real consequences beyond the annotations: the change affects LIVE call handling immediately and callers get routed differently. This is consistent with destructiveHint=true and idempotentHint=true rather than contradicting them. It stops short of stating permission/scope requirements or what happens to the previously active 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?

Three short sentences, front-loaded with "WRITE:" and the impact warning, then the id-discovery pointer, then the endpoint. No filler 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?

For a 2-parameter mutation with no output schema, the description covers purpose, live impact, prerequisite lookup, and the underlying endpoint. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining where number_id and profile_id come from (placetel_list_number_profiles) and framing profile_id as the profile to activate. It does not clarify units/formats, but the schema already does.

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: "switch the active routing profile of a phone number", with concrete examples (Holiday or Night). It is clearly distinct from the read-only sibling placetel_list_number_profiles, which is explicitly named as the id-lookup tool.

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 tells the agent exactly what to do first ("Find ids with placetel_list_number_profiles") and states the operation context (changing active routing profile). There is no explicit when-not guidance or mention of an alternative mutation path, but for this operation no competing sibling exists.

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 WRITE semantics, non-destructive behavior, non-idempotency, and open-world scope. The description adds useful behavioral context by clarifying that nothing is sent to the contact and by naming the POST /contacts endpoint.

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

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

The description is three short sentences, front-loads WRITE, and has no redundant or wasted phrasing. It communicates purpose, minimum input, side effect, and endpoint efficiently.

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

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

For a create tool with many optional fields, the description covers purpose, minimum input, side effects, and endpoint while annotations cover safety and open-world behavior. It does not describe the response, but no output schema exists and the key invocation constraints are present.

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

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

Schema coverage is 100%, so the schema already documents all 16 contact fields. The description still adds meaningful semantics by stating a minimum requirement of at least a name, company, or number, which the schema itself does not enforce via required fields.

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: create a contact in the shared Placetel phone book. It clearly distinguishes creation from sibling operations like get_contact, list_contacts, and update_contact.

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 creation context and a minimum data requirement: at least a name, company, or number. It does not explicitly route away from update_contact for existing contacts, but the create-vs-update distinction is clear from the verb and sibling 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that the result is scoped to the calling API key's identity and enumerates the returned fields, which is genuinely useful, but says nothing about auth requirements, error cases, or response shape beyond the field list.

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

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

A single dense sentence that front-loads the resource and its scoping, followed by the field inventory and endpoint. No filler, no repetition of the title.

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 carries the return-value burden and does so by listing the expected fields, which is the right compensation. Minor gap: it does not indicate how the 'numbers the key may use' collection is structured or bounded.

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 is 4. The description correctly signals a no-argument call by identifying it as a plain GET /me, leaving nothing ambiguous about 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 ('Get account'), enumerates exactly what the response contains, and pins it to the endpoint GET /me. It is clearly distinct from siblings like placetel_list_users or placetel_get_sip_user, though it never explicitly contrasts itself with them.

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 rather than stated: the mention of 'this API key' and 'the numbers the key may use' hints at an identity/discovery role, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. list_numbers for the full number inventory).

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, destructiveHint=false and openWorldHint, so safety is covered. The description adds real context beyond that: this returns only *incoming* calls and the exact field set, which matters because there is no output schema. It stops short of noting error behavior for a missing id.

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

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

Two short sentences, zero filler, and the identifying scope ('one incoming call by id') is front-loaded ahead of the field list and endpoint.

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 single-record GET with full schema coverage and annotations, the description is nearly sufficient, and enumerating return fields compensates for the absent output schema. Minor gap: no mention of what happens when the id doesn't resolve.

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 a single parameter at 100% schema coverage, the schema already documents call_id, its type, and its provenance. The description only repeats 'by id' and adds no format or constraint detail beyond the schema, 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 ('One incoming call by id') and enumerates the fields returned (caller, called number, type, duration, contact, voicemail URL), plus the underlying REST path. An agent can distinguish it from placetel_list_calls without opening either schema.

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

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

Usage is implied by 'by id', and the schema notes the id comes from placetel_list_calls, but the description itself names no alternative or exclusion. It never says what to do if the id is unknown or why to prefer this over list_calls.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the description needn't restate it. "With all its fields" adds a small useful signal about response completeness, but nothing is said about behavior when the id does not exist or is not visible to the caller.

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 waste, with the core operation front-loaded and the endpoint as supporting detail.

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

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

For a single-parameter read tool with full schema coverage and safety annotations, this is essentially complete; the only unaddressed area is lookup-failure behavior, which is minor given the simplicity.

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 sole parameter is documented as "Placetel contact id (from placetel_list_contacts)", which already explains provenance and type. The description's "by id" adds nothing beyond that, so baseline 3 applies.

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

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

States a specific verb+resource: retrieves one contact by id, plus the underlying endpoint GET /contacts/{id}. The phrase "One contact" implicitly contrasts with placetel_list_contacts, though that sibling is never named 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 only implied: an agent can infer that this is the single-record fetch versus the list sibling, especially since the schema says the id comes from placetel_list_contacts. There is no explicit when-to-use/when-not statement or prerequisite note.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context by enumerating the returned attributes and naming the endpoint, which matters because there is no output schema; it still omits not-found/error 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?

The description is compact and front-loaded: it identifies the tool as fetching one fax by id, then lists the payload fields, then gives the endpoint. Every clause carries useful information and there is no filler.

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

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

For a simple one-parameter read operation with annotations and full schema coverage, the description is mostly complete: it explains the resource, returned fields, and endpoint. It could be stronger by mentioning not-found behavior or confirming that all listed fields are always present.

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

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

Schema description coverage is 100%, and the single fax_id parameter is documented as coming from placetel_list_faxes. The description adds only the phrase 'by id' and no additional format or constraint details beyond the schema, 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?

States the resource and scope precisely: one fax by id, plus the fields returned and the underlying GET endpoint. It is clearly distinguishable from placetel_list_faxes by the 'one fax by id' framing, though it does not explicitly name the sibling alternative.

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

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

The description implies usage when a specific fax id is known, and the schema points to placetel_list_faxes as the id source. However, the description itself gives no explicit when-to-use guidance, prerequisites, or alternative-tool routing.

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 safe read operation (readOnlyHint=true, destructiveHint=false), so the description's job is to add context. It does so by enumerating the returned fields (number, E.164, name, site, carrier, activation state, routing id) and noting the underlying GET endpoint, which is useful for a tool with no output schema. It does not mention error behavior for a missing id.

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 short, front-loaded fragments with no filler. The 'GET /numbers/{id}' suffix is somewhat redundant with the tool name and annotations, but the field list is compact and informative.

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 single-resource read tool with full parameter schema coverage and read-only annotations, the description provides enough context: what it retrieves, by what key, and what fields come back. Error behavior and pagination are not relevant, though a note on missing ids could improve completeness.

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

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

Schema description coverage is 100% and the single parameter's schema already says 'Placetel number id (from placetel_list_numbers)'. The description only implies the id lookup and adds no syntax or format detail beyond the schema, 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 states a specific resource (one phone number) and the lookup key (id), and enumerates the returned fields. It implicitly distinguishes itself from placetel_list_numbers by saying 'One phone number by id', though it does not name the list 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?

Usage is only implied: retrieve a single number when you have its id. There is no explicit when-to-use, when-not-to-use, or named alternative such as placetel_list_numbers for discovering ids.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP path and the dual-key lookup, but says nothing about error behavior (e.g. unknown id) or what the returned routing object contains.

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

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

Two compact sentences with the capability front-loaded and the endpoint/method appended as supporting detail. Nothing is 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?

A single-parameter read tool with annotations and a fully documented schema needs little more; the description is sufficient to call it correctly. The only gap is no hint about the shape of the returned routing object, which matters slightly given there is no 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 coverage is 100% and the parameter already documents acceptable id and phone-number formats with examples. The description restates the same either/or without adding format, normalization, or precedence rules, so baseline 3 applies.

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

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

States a specific verb and resource — retrieving a single routing object — and names the two lookup keys. Saying 'One routing object' implicitly contrasts with placetel_list_routings, but no sibling is named 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?

The description makes clear this is a single-record fetch keyed by id or phone number, which implies when to use it over the list tool, but it never states that condition or mentions placetel_list_routings as the alternative for enumeration.

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

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

Annotations already declare readOnlyHint and non-destructive, so the description earns credit for adding what the annotations do not: the exact data surface returned, the explicit guarantee that 'SIP password and PINs are never returned', and the underlying REST endpoint. That masking note is genuinely useful behavioral context for an agent assembling a response.

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 no filler; the returned-field list is front-loaded and the sensitive-field exclusion follows immediately. The trailing 'GET /sip_users/{id}' is mildly redundant but cheap and useful for traceability.

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 enumerating the returned fields (sipuid, extension, caller id, type, linked web user, online state, call settings) is exactly the right compensation, and the security note closes the obvious gap. Only the absence of any usage/error guidance keeps it short of a 5.

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

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

Schema coverage is 100% and the sole parameter is documented there, including the pointer to placetel_list_sip_users as the source of ids. The description adds only 'by id', which restates the schema rather than extending it - 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 retrieval: 'One SIP user (extension) by id', followed by the fields it surfaces. The singular 'one ... by id' scoping implicitly separates it from the list sibling, though it never names placetel_list_sip_users 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 only implied by 'by id' - an agent can infer this is the detail lookup after listing. There is no explicit statement of when to use this versus placetel_list_sip_users, nor any prerequisites or error conditions.

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

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

Annotations only say readOnly=false, openWorld=true, idempotent=false, destructive=false. The description goes well beyond by disclosing the two-leg ring-then-dial sequence, that a real call is placed, and that call charges apply — the crucial non-obvious side effect that destructiveHint=false does not convey. The POST /calls endpoint is a bonus.

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 with the WRITE marker and the safety warning front-loaded, then mechanism, then endpoint. Every sentence carries distinct information; nothing is redundant.

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 mutation semantics, cost, prerequisite intent, and the ring-first flow — enough to call it safely. It omits what the call returns (e.g. a call ID usable with placetel_get_call), which matters given there is no output schema, but that is a minor gap.

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

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

Schema coverage is 100%, so the schema already documents sipuid (with an example and a pointer to placetel_list_sip_users), target, and from_name. The description only loosely refers to 'the given SIP user's phone' and 'the target number', adding no format or constraint detail beyond the schema — baseline 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 ('start a real phone call') and explains the exact mechanism: Placetel rings the SIP user first, then dials the target once answered. This is unmistakably distinct from sibling tools like placetel_send_sms or the placetel_list_* readers.

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?

'Do not use without the user's explicit request' is an explicit when-not condition, and the charge warning adds a further gate. It stops short of naming a preferred alternative flow (e.g. confirming via placetel_list_sip_users first), but the guidance is clear and actionable.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint and the returned field set but says nothing about pagination behavior or result volume, which the schema only partially covers.

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, purpose first, endpoint second, with zero filler. Every word 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, listing the returned fields is genuinely useful and largely fills the gap for a simple read-only list endpoint. Paging behavior lives in the schema, so little is missing, though a note on empty-page termination would have made it 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?

Schema description coverage is 100% with only two optional paging parameters, both already documented in the schema including the next_page chaining hint. The description adds no parameter semantics, 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 ('List call-center agents') and enumerates the fields returned (name, status, extension, priority, last call time), plus the underlying endpoint. It is clearly distinct from siblings like list_call_center_queues and list_call_center_calls, though it never names an alternative to route against.

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 guidance, no mention of when to pick agent lists over queue or call lists, and no stated prerequisites. The agent must infer everything 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond that by enumerating the returned attributes (queue, agent, answer status, queue wait time), which is the main thing an agent needs to know before calling; pagination caveats live 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?

Front-loaded with the resource and its scope, then the two operational constraints, in two tight sentences. The trailing "GET /call_center_calls" is endpoint trivia that earns little, but it is a single clause.

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 listing the reported fields is exactly the right compensation, and paging is covered in the schema. The only gap is the absence of any routing hint versus the sibling call-listing tools, which matters in a catalog this size.

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 all four parameters are already documented, including the pattern for date and the paging contract. The description reinforces which parameter is mandatory and the intent of queue_ids but adds no format or syntax detail beyond the schema — baseline 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 resource (call-center calls for one day) and enumerates the dimensions reported (queue, agent, from/to, answer status, timings). It implicitly distinguishes itself from the general placetel_list_calls by scoping to call-center calls, though it never names that 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?

"date is required; narrow to queues with queue_ids" gives the core invocation constraints, and the queue reference points to placetel_list_call_center_queues for id discovery. However, there is no guidance on when to prefer this over placetel_list_calls or placetel_list_call_detail_records, which an agent must infer.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the HTTP endpoint and the shape of returned fields, but says nothing about pagination behavior or ordering, leaving that entirely to 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?

Three short sentences, front-loaded with what is listed and what fields come back, with zero filler. The endpoint reference is compact and useful for agents that reason about REST paths.

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 carries the burden of describing return values, and it does so by naming the fields. Paging semantics live in the schema. Only ordering and empty-page termination guidance are absent, which is minor.

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

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

Schema description coverage is 100%, and both page and per_page are documented in the schema including the next_page paging hint and per-page caveat. The description adds no parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (list call-center queues) and enumerates the returned fields (name, ring time, loops, prompts), which distinguishes it from the sibling list_call_center_agents and list_call_center_calls tools. It stops short of explicitly naming those siblings, so differentiation is inferential rather than spelled out.

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?

'Use the ids to filter call-center calls' gives a downstream purpose hint but not a when-to-use/when-to-avoid rule or a named alternative. The agent must infer that this tool is the lookup step before filtering calls by queue id.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the useful framing that these are billing-view records (implying cost fields, not raw telephony detail) and the one-day scope, but says nothing about result volume, paging behaviour, or whether empty days return empty pages.

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 naming the resource and its fields, plus the required-parameter note and the endpoint path. No filler, nothing redundant with structured data beyond a harmless restatement of requiredness.

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 and read-only annotations, the only open question is what comes back; the field list compensates for the absent output schema. Paging semantics are delegated to the schema, which documents them, so nothing essential is missing.

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

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

Schema description coverage is 100% – date, page and per_page are all documented in-schema with formats, ranges and paging advice. The description only repeats 'date is required', adding no meaning beyond the schema, 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+resource ('call detail records (billing view) for one day') and enumerates the returned fields (from, to, answering SIP user, length, cost). It implicitly distinguishes this from placetel_list_calls but never names that sibling or contrast the two, so a 4 rather than 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?

'for one day' and 'date is required' imply the usage context, and the billing-view framing hints why an agent would pick this over a general call list. However it never states when to prefer placetel_list_calls instead, nor any exclusions, so guidance is only 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?

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real value by disclosing the return fields (caller, called, duration, contact match, voicemail URL, unread flag) even though no output schema exists, and by stating the today-by-default window. Pagination behavior is left to the schema rather than the description.

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 with the scope and default front-loaded, followed by return payload then the date override. The trailing "GET /calls" is minor implementation detail rather than agent-relevant 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 seven optional params, no output schema, and full schema coverage, the description covers what is needed: scope, default window, filter vocabulary, and the shape of results. Missing only explicit paging/volume expectations, which the schema already hints at.

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 all seven parameters are documented in structured form; baseline is 3. The description adds only a light restatement of the date default and the outcome filter vocabulary, without new syntax or format semantics 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?

Specific verb (list) plus resource (incoming calls) plus scope (one day, today by default) and an enumeration of the outcome states covered. It is clearly distinguishable from placetel_get_call or placetel_list_call_center_calls by implication, but no sibling is named 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?

"For a different day pass date" gives one concrete usage cue and the default-day behavior is stated, so day-based selection is clear. However, there is no guidance on when to prefer placetel_get_call (single call) or placetel_list_call_detail_records (history/CDR), and no 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it states the contacts are from a 'shared phone-book' (shared scope), enumerates the returned fields in lieu of an output schema, and identifies the underlying endpoint GET /contacts. It does not discuss pagination behavior or result limits.

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 compact sentences with the purpose front-loaded, followed by filter capabilities and the endpoint. There is little waste, though the trailing 'GET /contacts' is a marginal detail and the filter summary slightly duplicates what the schema already conveys.

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 16 optional parameters, no output schema and solid annotation coverage, the description does the needed work by enumerating return fields and framing the tool as a filtered list over a shared phone book. Pagination semantics are left to the schema's page/per_page descriptions, which is a minor gap but not a blocker.

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 all 16 parameters in detail, and the description only summarizes the filterable fields (name, company, email, number, update time). It omits several parameters entirely (blocked, speeddial, page, per_page, the *_work variants) and its note on search_number largely repeats the schema text. 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 opens with a specific verb and resource ('List the shared phone-book contacts') and enumerates what each record contains (names, company, numbers, emails, tags, blocked flag), which tells an agent exactly what it gets back. It stops short of naming sibling tools like placetel_get_contact or placetel_create_contact, so the read-vs-single-record distinction is only implied.

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?

'Filter by name, company, email, number or update time' plus 'search_number finds a contact by any of its numbers' gives implied usage context for lookup scenarios. However, there is no explicit when-to-use guidance, no exclusions, and no pointer to the sibling tools (get_contact, create_contact, update_contact) that an agent would otherwise have to disambiguate from names alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context by enumerating the returned fields (numbers, status, pages, duration, type, file URL) and noting the endpoint path. It does not mention pagination behavior, though the schema covers page/next_page.

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 plus the endpoint, with the resource and its payload fields front-loaded before the filter note. No filler, though the trailing 'GET /faxes' is marginal 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?

With no output schema, the description usefully enumerates what a fax record contains, which is the main thing an agent would otherwise lack. Pagination and limits are fully covered by the schema, so the only gap is explicit routing away from placetel_get_fax.

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 including enums is documented in the schema. The description only restates the two filter dimensions (direction, number) without adding syntax, defaults, or format details, so it sits at the baseline.

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 the specific resource (in- and outbound faxes), enumerates the fields returned, and names the filter dimensions, so it is clearly a listing operation distinct from the singular placetel_get_fax. It lacks an explicit contrast with that sibling, but the plural scope plus filter language makes the distinction inferable.

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?

'Filter by direction or number' implies the usage context (browsing a fax log rather than fetching one record), but there is no explicit when-to-use guidance or stated alternative such as placetel_get_fax for a single fax. Usage must be inferred from the verb and scope.

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, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds the underlying 'GET /groups' mapping and discloses that members are returned with each group. It stops short of noting rate limits or result ordering, but the important behavioral facts are present.

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

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

Three short sentences with the verb and resource front-loaded; little waste. The trailing 'GET /groups' is a REST routing detail that earns marginal space for an agent that just needs to invoke the 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?

No output schema exists, and the description partly compensates by saying results include members; pagination semantics are carried by the schema. For a zero-required-parameter, read-only list endpoint this is close to sufficient, though return shape beyond 'members' remains unspecified.

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 name, description, type, page and per_page are fully documented in structured fields, including the 'pass next_page' and 'keep paging until a page is empty' hints. The description only restates the three filter fields and adds no syntax or semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List ring groups') and enumerates the concrete group types (ring_all, hunt, monitoring), which no sibling tool covers. The addition 'with members' tells the agent what the listing contains, so it is separable from list_routings or list_users 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?

'Filter by name, description or type' implies how to narrow results but never states when this tool is the right choice versus nearby reads such as placetel_get_routing or placetel_list_routings. No sibling overlap makes this low-risk, but the guidance is implied rather than 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the plan-requirement constraint and the exact endpoint, but says nothing about error shape, empty results, or whether inactive profiles are included.

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

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

Two compact sentences plus the endpoint, with the returned data front-loaded. Nothing is wasted, though the opening noun phrase reads as a fragment rather than a crisp statement of the operation.

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

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

For a one-parameter read-only lookup with no output schema and fully covered annotations, the description covers the returned content and the main precondition. Only the source of number_id and the failure mode for non-profile plans are left implicit.

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% for the single number_id parameter, so the baseline is 3. The description adds no meaning beyond the schema — it does not say where number_id comes from (e.g., placetel_list_numbers) or how it behaves.

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

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

The description names the specific resource (routing profiles of a phone number) and the returned fact (which profile is active), which distinguishes it from the sibling action tool placetel_activate_number_profile. The verb is only implicit in the noun-phrase phrasing, but the GET endpoint and title make the read/list nature 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?

It supplies a real prerequisite ('Needs a Placetel plan with number profiles') that tells the agent when the call will fail. However, it never states when to use this versus placetel_activate_number_profile or how it relates to placetel_get_number / placetel_get_routing, so usage is only 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value by enumerating returned fields (E.164 form, activation state, routing object id) since there is no output schema, but it says nothing about pagination, result caps, or the per_page caveat beyond what the schema states.

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 that names the resource then the returned shape; no filler. The trailing 'GET /numbers' is a minor, low-value addition but does not dilute the content.

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

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

With no output schema, describing the returned field set is exactly the right compensating information, and the schema fully carries the filters. The remaining gap is that nothing tells an agent how to interpret an empty result or the interaction with activation state filtering across plans, but that is a minor omission for a list 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% and each of the 8 filter parameters is documented in the schema, including the paging caveat and the site_id cross-reference. The description adds no parameter meaning beyond the schema, 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 ('List the phone numbers of the account') and enumerates the fields returned, which makes the tool's output scope concrete. It doesn't explicitly contrast itself with the sibling placetel_get_number (single-number lookup) or placetel_list_number_profiles, so sibling differentiation is only implied.

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 placetel_get_number for one number or placetel_list_number_profiles for profiles. The only narrowing hint ('GET /numbers') is an endpoint reference, not a usage rule, and the filter conditions live entirely in the schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without the description. The description reinforces that this is a plain GET read and adds the returned field set, but says nothing about pagination behavior (which lives in the schema) or rate limits. With annotations doing the heavy lifting, a 3 is appropriate.

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, front-loaded sentences with the returned fields stated first, then filtering, then the endpoint. Nothing is wasted, though the trailing "GET /recordings" is more implementation detail than agent guidance.

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, read-only list tool with no output schema, the description covers what is returned and what can be filtered, which is what an agent needs to select and invoke it. Pagination and ordering details are adequately handled by the schema descriptions.

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 one of the 7 parameters is already documented in the schema, including paging, ordering, and the direction enum. The description's mention of direction/number/day filters maps to the schema but adds no semantics beyond it. 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 resource (call recordings), the fields returned (direction, from, to, duration, time, file URL), the filter axes, and the backing endpoint. It is a clear verb+resource statement. It does not, however, distinguish this tool from near-siblings like placetel_list_calls or placetel_list_call_detail_records, which an agent could plausibly confuse with recordings.

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?

"Filter by direction, number or day" implies when the tool is useful, but there is no explicit when-to-use versus alternatives and no mention of the sibling call-listing tools. Usage has to be inferred from the filter list 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description need only add context beyond that. It does so by naming the backing endpoint (GET /routing_plans) and enumerating the fields returned (name, description, ring duration, object counts), which matters because no output schema exists.

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 front-loaded sentence with the resource gloss and returned fields, plus the endpoint path. Nothing is padded, though the trailing 'GET /routing_plans' is near-redundant with the tool name.

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 read-only list tool with no output schema, the description supplies the essential missing piece: the shape of the returned records. The remaining gap is any hint about how this differs from the sibling list_routings 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 coverage is 100% and both pagination parameters carry detailed descriptions, including the 'keep paging until a page is empty' caveat, so the schema does the heavy lifting. The description adds nothing about paging or limits beyond what is already in the schema; baseline 3 applies.

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

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

Names a specific verb+resource and goes further by glossing the resource as 'time-based call distribution plans', which an agent could not infer from the name alone. It does not, however, distinguish this from the confusingly similar sibling placetel_list_routings, so sibling disambiguation is left to inference.

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 placetel_list_routings or placetel_get_routing, and no prerequisites or exclusions. The agent must infer from the name that this is a browse/list operation for a distinct resource type.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds the HTTP endpoint and the update-time filter, which is useful context, but says nothing about ordering, result size, or what the returned settings/time settings look 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?

Two compact sentences plus the endpoint, front-loaded with the resource and its meaning, and the update-time filter is stated immediately after. Nothing is 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?

As a read-only list endpoint with full schema coverage, no output schema, and per-page hints already in the schema, the description covers enough to call it correctly. Minor gap: it doesn't hint at what the returned settings entail, though that is a small omission for a list 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 page, per_page, updated_since, and updated_until fully documented in the schema. The description's "Filter by update time" merely echoes those fields, so baseline 3 is appropriate – no additional format or semantics are contributed.

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 routing objects") and adds a parenthetical that explains what a routing is (forward, group, routing plan, IVR, queue, voicemail, API), which clearly separates it from generic list tools. It doesn't directly name siblings like placetel_get_routing or placetel_list_routing_plans, so the differentiation is implicit rather than explicit.

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

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

"Filter by update time" and the underlying GET /routings endpoint imply the usage context (bulk retrieval with incremental sync), but there is no explicit when-to-use guidance, no statement about when to prefer placetel_get_routing for a single object, and no mention of pagination strategy beyond what the schema carries.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: exactly which fields come back and the security guarantee that "SIP passwords and PINs are never returned", which is not derivable from any structured field.

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 front-loaded sentences that lead with the verb and resource, then disclose the return fields and the password guarantee. The trailing "GET /sip_users" is minor low-value filler for an agent but costs only a few tokens.

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 response, and it does enumerate the returned fields (did, caller id, type, online state, registrations) plus the deliberate omissions. Pagination and filter semantics are handled in the schema, so nothing essential is missing, though it never mentions that results can be filtered at all.

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 all six filters (did, name, username, description, page, per_page) are already documented; baseline is 3. The description only glosses "extension number (did)", which mildly clarifies the did parameter but adds no syntax or filtering-combination guidance 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?

States a specific verb+resource ("List SIP users") and disambiguates the resource by enumerating what a SIP user actually is: phone extensions, softphones, fax and trunk lines. It also names the returned fields, so the agent knows this is the enumeration endpoint rather than the single-record placetel_get_sip_user, though that sibling is never called out by name.

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 says nothing about when to call this versus placetel_get_sip_user or the other list_* siblings, and never mentions the available filters, so an agent gets no routing guidance. The plural "List" implies enumeration, but that is left entirely to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that results include address and prefix, which is mild return-content context, but says nothing about result volume or that paging may need to continue until empty.

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, front-loaded sentences with no filler. The trailing 'GET /sites.' is marginal but useful for an agent reasoning about the underlying API surface.

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 endpoint with full parameter documentation and annotations covering safety and open-world behavior, the description is adequate. Only pagination behavior is absent from the description, and the schema already flags it.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are documented with defaults and the 'keep paging until a page is empty' caveat in the schema itself. The description contributes nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List company sites (locations)') plus the fields returned (address, prefix). The resource is inherently distinct from sibling list tools like numbers, users, or contacts, though no sibling is named 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?

No when-to-use guidance, no prerequisites, and no alternatives referenced. The only context is the endpoint string 'GET /sites.', which tells the agent nothing about selection between this and the other placetel_list_* tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds that results are paginated account users and enumerates the fields returned, plus the underlying GET /users endpoint, but says nothing about pagination depth or the non-honored per_page, which the schema carries instead.

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 is listed and what it returns. The filter sentence and the trailing 'GET /users' partially duplicate the schema, but no sentence is wasted at any real length.

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 enumerates the returned fields (name, email, login, type, permissions, numbers), and all seven filter/paging parameters are documented in the schema. Combined with annotations covering the read-only profile, an agent has what it needs to call this 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 every parameter including page, per_page and first_name/last_name is already documented. The description only restates a subset of filter fields ('name, email, login or type'), adding no syntax or behavior beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List the web users of the account') and enumerates the returned fields, which distinguishes it implicitly from placetel_list_sip_users by scoping to 'web users' including main account and sub-users. It never names the SIP-user sibling explicitly, so the differentiation is inferential rather than stated.

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 filter sentence ('Filter by name, email, login or type') implies how to narrow results, and the 'web users' framing hints at the SIP-user alternative, but there is no explicit when-to-use/when-not guidance or named alternative. An agent must infer the choice between list_users and list_sip_users.

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

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

Goes well beyond the annotations: it discloses real-world side effects (the recipient receives it immediately), monetary cost ('SMS charges apply'), irreversibility ('cannot be recalled'), and an authorization precondition. The annotations only mark it non-readonly, non-idempotent and open-world, so this description is what actually conveys the stakes.

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 operation class and the verb, then cost/irreversibility, then the usage gate, then endpoint. No filler and every clause carries decision-relevant 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 two-parameter, no-output-schema write tool with annotations present, the description covers preconditions, cost, and irreversibility well. It doesn't say what the call returns (message ID, delivery status), which is the only notable omission since no output schema exists to cover it.

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 with pattern and length bounds. The description reinforces 'exact text' and the phone-number recipient, but adds no format, encoding, or segmentation detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('send a real SMS to a phone number from the Placetel account') and prefixes the mode ('WRITE:'), making it instantly distinguishable from the read-oriented list/get siblings and from placetel_initiate_call. An agent can pick this tool 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?

Gives explicit when-not guidance: 'Do not use without the user's explicit request and exact text', which is a concrete gating condition rather than a vague hint. It doesn't point to an alternative channel (e.g. placetel_initiate_call for voice) but none of the siblings offer an SMS substitute, so the gap is minor.

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 destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description still earns credit by explaining the concrete mechanics behind that destructiveness: an empty string clears a text field, tags replaces the entire list, and blocked=true blocks the caller's calls — side effects an agent could not infer from annotations alone.

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 compact sentences, front-loaded with the WRITE classification, followed by patch semantics and the endpoint. Every clause carries operational information; nothing is redundant with the tool 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 17-parameter mutation with no output schema, the description covers the essential update semantics and the destructive side effects. It stops short of noting what the response returns or any authorization requirements, but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and every parameter is already self-documented. The description adds genuine update semantics the schema does not state: omitted fields remain unchanged and empty strings clear text fields, which is critical for correctly invoking a PATCH-style update across 17 fields.

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?

Opens with an explicit verb+resource ("update the given fields of a contact") plus a WRITE marker, making the mutation intent unmistakable against read siblings like placetel_get_contact and placetel_list_contacts. It also disambiguates from placetel_create_contact by specifying field-level patching of an existing record.

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 through the patch semantics ("omitted fields stay") and the WRITE prefix, which signals this is for modifying existing contacts rather than creating them. However, there is no explicit statement of when to choose this over placetel_create_contact, nor any prerequisite or exclusion guidance.

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