Rinkel MCP by usefulapi

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, so the safety profile is covered. The description adds genuine context beyond that: notes are 'visible to everyone in the account who sees the call', the specific 404 retry path, and the underlying PUT endpoint. It does not address permission requirements or duplicate-note behavior on retry, but the added operational detail is substantive.

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 WRITE: marker, no filler. Every clause carries information: operation scope, visibility, identifier fallback, 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 two-parameter mutation with full schema coverage, functional annotations, and no output schema, the description supplies what an agent needs: what it writes, who sees it, how to resolve the id, and how to handle a 404. Missing only marginal items such as whether multiple notes can coexist or what a success response looks like.

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. The description earns above baseline by telling the agent that `id` is the primary identifier and that the record's `callId` should be tried when Rinkel answers 404 — a resolution rule the schema does not state.

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 ('add a note to a call record') and leads with a WRITE: marker, making the operation type immediately clear. It implicitly separates itself from update_call_note and delete_call_note, though it never names them explicitly.

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

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

Usage is implied by the note-adding framing, and there is useful edge-case guidance for the 404 path (retry with the record's `callId`). However, no sibling alternatives are named and there is no explicit statement of when NOT to use this versus update_call_note, so a substantial part of the guidance burden 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 cover the safety profile (idempotent, non-destructive write), and the description adds genuinely new behavioral information: that a wildcard must terminate the value and include a country code, and that a broad wildcard blocks every caller from an entire country — a real blast-radius warning. The endpoint reference is a bonus for debugging.

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

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

Three dense sentences, each doing distinct work: operation and scope, accepted value forms and their risks, undo path plus endpoint. Front-loaded with the WRITE marker and no filler.

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

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

For a two-parameter mutation with no output schema, everything an agent needs is present: accepted input forms, wildcard edge cases, reversibility, and the API surface. Nothing material is omitted.

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. The description earns a bump by elaborating wildcard semantics beyond the schema's one-line hint — the 'must end the value' and 'broad wildcard blocks a whole country' constraints are not apparent from the schema alone.

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 ('block a number') plus the exact scope ('from calling ANY of the account's numbers'), which distinguishes it cleanly from the many read/list siblings. The 'WRITE:' prefix further signals mutation at a glance.

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

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

Explicitly routes the agent to rinkel_unblock_number as the inverse operation, giving clear when-to-use context. It stops short of naming prerequisites (e.g., whether the number must first be validated via rinkel_validate_phone_number) or exclusions, so not quite 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?

readOnlyHint=true already tells the agent this is a safe read; the description adds the useful semantic definition of 'new' (not yet played) and cites the underlying endpoint GET /voicemails/new-count. It says nothing about scoping (per-user/account-wide) or the return shape, but with annotations covering safety this is a minor gap.

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

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

Two sentences, zero waste, front-loaded with the meaning of the result before the endpoint reference. Nothing could be removed without losing 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 trivial zero-param read with no output schema, the description conveys enough: the result is a count of unplayed voicemails. Only the scoping of the count (whose voicemails) is left unstated, a small but real 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?

Zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing filtering options that do not exist.

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+resource (counting voicemails) and sharpens it with the qualifier 'that have not been played yet', which defines what 'new' means. It does not explicitly contrast with rinkel_list_voicemails, but the count-vs-list distinction is legible without opening a 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 only implied: an agent can infer this is the cheap badge/notification check versus rinkel_list_voicemails for full records, but the description never says so or names the alternative. No exclusions or preconditions are given, which is acceptable for a zero-parameter read.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-annotation context: the contact is shared with everyone in the Rinkel account, and calls from its numbers display its name. This goes beyond structured fields, though it does not explain duplicate-contact behavior.

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

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

Two tightly written sentences front-load the write operation and then add sharing scope and the API endpoint. The API endpoint may be marginally less useful to an agent, but overall there is no wasted prose.

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 key sharing side effect but omits important details such as duplicate handling, whether the contact can be edited later, and the significance of the required numbers array. Annotations cover safety, but the low parameter coverage leaves gaps.

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

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

Schema description coverage is only 33%, so several parameters lack documentation in both schema and description. The description references 'numbers' only through the sharing behavior and does not explain the required numbers array, default_outbound_number_id, or the name/company fields. It fails to compensate for the low schema coverage.

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

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

The description states a specific verb and resource: 'WRITE: create a contact.' It clearly distinguishes creation from sibling tools like rinkel_update_contact and rinkel_list_contacts, so an agent can identify its purpose 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?

The 'WRITE' prefix and 'create a contact' imply this should be used when adding a new contact, but the description does not explicitly say when to use this versus rinkel_update_contact or how to check for duplicates. Usage is implied rather than guided.

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 destructiveHint=true and idempotentHint=true, so the description's added 'WRITE, irreversible' is reinforcement rather than new information. The genuinely additive detail is the required user-approval gate before setting confirm=true, which is a workflow constraint annotations cannot express.

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

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

Two tight sentences, with the write/irreversible warning and confirmation requirement front-loaded before the API 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?

For a destructive 3-parameter mutation with no output schema, the description covers irreversibility, the confirmation gate, and the endpoint. It does not describe failure/error behavior or what happens if the note id is already gone, 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% and each parameter already has its own description, so the schema carries the load. The description adds only the confirm-after-approval semantics, which the schema also states, so it does not go meaningfully beyond it.

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 ('delete one note from a call record') and even names the underlying API operation and path. It is unambiguous against siblings like rinkel_update_call_note or rinkel_add_call_note.

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

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

Gives a clear precondition for invocation: 'Needs confirm=true after the user approved it,' which tells the agent exactly when this tool is legitimate. It does not explicitly point to alternatives (e.g., update vs delete), but the scope is narrow enough that inference is easy.

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 annotations (destructiveHint=true, idempotentHint=true), the description discloses irreversibility, the account-wide blast radius, and the exception that the Rinkel system contact cannot be deleted. It also narrates the human-approval gate, which is the key behavioral constraint for a destructive tool.

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

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

Three short sentences, each carrying distinct information: mutation class and scope, confirmation requirement, protected-record exception. The most decision-relevant fact (WRITE, irreversible) is first.

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 destructive tool with no output schema, everything an agent needs to invoke it correctly is present: safety profile, scope, approval protocol, and the blocking edge case. Nothing essential is deferred to structured fields.

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; the description adds value by constraining which contact_id values are valid (the system contact is rejected) and by reinforcing the semantics of the confirm flag as an approval gate rather than a generic boolean.

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 a specific verb and resource ('delete a contact') qualified by scope ('for the whole account') and the exact API operation (DELETE /contacts/{id}). It is unambiguous against siblings like rinkel_update_contact or rinkel_get_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?

Gives a clear procedural precondition: confirm=true only after the user approved this exact action, which tells the agent when it may proceed. It does not, however, point to alternatives (e.g. update_contact) or describe when deletion is preferable to other resolution paths.

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 read-only safety profile, and the description adds genuinely new behavior: a 404 result when no contact owns the number. That error semantics is the main operational fact an agent needs beyond the annotation.

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

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

Two short sentences with zero padding; the core action, the format hint, the miss behavior, and the endpoint are all front-loaded and each earns its place.

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

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

For a single-parameter read tool this covers action, format, and failure mode. With no output schema, a note on what the returned contact contains would fully close the gap, but it 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?

Schema coverage is 100% and the phone_number field already documents E.164 preference with an example. The description repeats that same hint ('+31612345678 works best') without adding format rules, normalization behavior, or what happens with non-E.164 input, so it stays at 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 a specific verb+resource: 'Find the contact that owns a phone number.' This clearly separates it from rinkel_get_contact (ID lookup) and rinkel_list_contacts, even though no sibling is named explicitly. The endpoint path reinforces the scope.

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

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

Usage is implied by the lookup framing and the 404 note tells the agent what a miss looks like, but it never says when to prefer this over rinkel_get_contact or rinkel_validate_phone_number. An agent must infer the routing itself.

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

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

Annotations already declare `readOnlyHint: true`, so the safety profile is covered. The description adds real behavioral context by listing the returned details (numbers, users, status, duration, notes, voicemail and recording ids, AI insights) and naming the underlying API endpoint, which helps the agent understand the response shape even without an output schema.

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

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

The description is two compact sentences with no wasted wording. The core purpose and id source are front-loaded, followed by return-field details and the 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-parameter read tool, the description provides the essential purpose, id source, return contents, and endpoint. It does not mention not-found behavior or invalid-id handling, but with read-only annotations and a fully documented schema, nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% and the parameter is already documented as the call detail record id. The description adds meaningful provenance by tying it to the `id` field returned by `rinkel_list_calls`, which is more useful than repeating the schema text alone.

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 - get one call detail record - and identifies the exact id provenance (`id` field from `rinkel_list_calls`). It implicitly distinguishes itself from `rinkel_get_call_by_network_id` by specifying the Rinkel id rather than a network id.

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

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

It clearly explains where to get the required id (`rinkel_list_calls`) and what the tool retrieves, giving an agent enough context to use it correctly. It stops short of explicitly contrasting with alternatives like `rinkel_get_call_by_network_id` or `rinkel_get_call_transcription`, so it lacks full when/when-not 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying endpoint path and the provenance of the id, but says nothing about behavior on a missing/unknown callId (e.g. 404 vs empty result) or about auth/rate-limit constraints.

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: the primary semantics and identifier source come first, the endpoint reference trails as supporting detail. Nothing is padded or 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?

For a two-parameter read with fully documented schema and a readOnly annotation, this covers what an agent needs to invoke it. The only real gap is what the response contains when the callId is unknown, which the absent output schema leaves to inference.

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% — both parameters are described in the schema, including that include_details covers insights and notes. The description reinforces the network_call_id provenance but adds essentially no syntax, format, or validation detail beyond the structured fields, 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 (get one call detail record) and pins down which identifier is needed — the network callId from webhook events — plus the exact REST endpoint. It stops short of naming sibling rinkel_get_call, so the distinction between looking up by network callId versus by internal record id must be inferred.

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 parenthetical '(the id Rinkel sends in webhook events)' implies the scenario where this tool applies, and 'optionally with insights and notes' hints that the second parameter is opt-in. However, no alternative tool is named and there is no explicit when-not-to-use guidance despite a very similar sibling (rinkel_get_call) in the set.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavior: the URL expires after 3 hours and appending a `download` query parameter switches from streaming to downloading. It does not say whether expiry means regeneration or failure, or note any rate limits, which keeps it short of a 5.

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

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

Three tight sentences, front-loaded with the outcome and expiry, then id provenance, then the download modifier, then the endpoint. Nothing is redundant or padded.

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

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

With no output schema, the description carries the return value and does so clearly (a temporary streaming/download URL, 3-hour lifetime). Only a note on what happens after expiry or how to obtain the recording id from a sibling call would make it fully 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 coverage is 100% and the single parameter is already documented as `callRecording.id`. The description repeats the same pointer without adding format, examples, or where to obtain the id, 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 a specific verb and resource ('Get a temporary URL ... to stream or download a call recording') and names the underlying API endpoint, so it is unambiguous next to siblings like rinkel_get_call or rinkel_list_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?

The audience is implied by 'callRecording.id of a call record', but the description never says when to reach for this instead of rinkel_list_recordings or rinkel_get_voicemail_url. No explicit exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavior beyond that: an account-level prerequisite and a specific error outcome (404). It doesn't describe the return shape, but for a single-purpose read tool that is a minor omission.

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: capability first, then the required account feature and error case. The trailing API route is extra but compact and adds traceability without bloat.

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 tool, the description covers the prerequisite, the error path, and what is returned (the raw transcription). Missing only pagination/format detail, which is unlikely to matter here.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, so the description only restates that the identifier is the network callId. Baseline 3 applies since the schema does the work.

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 the raw transcription of a call') scoped by its network callId, which the agent can distinguish from siblings like rinkel_get_call_recording_url or rinkel_get_call. It doesn't explicitly name those alternatives, but the resource is precise enough to route correctly.

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

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

Gives a real precondition (Rinkel AI insights must be enabled on the account) and an explicit failure condition (404 when the call has no transcription). These effectively tell the agent when the call will fail, though no sibling alternative is named for the no-transcription case.

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 readOnlyHint=true annotation already tells the agent this is a safe read. The description adds the underlying endpoint (GET /contacts/{id}), which hints at passthrough semantics, but says nothing about error behavior (e.g., not-found), permissions, or what the response 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 short sentences, purpose first and the endpoint mapping second. Nothing is wasted and the key information is front-loaded.

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

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

For a single-parameter read tool with a readOnly annotation, the definition covers what an agent needs to invoke it. The only real gap is that no output schema exists and the description doesn't characterize the returned contact fields, though that is minor at this complexity.

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 contact_id parameter, so the schema already carries the semantics. The description only restates that lookup is by id and adds no format, sourcing, or validation guidance.

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

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

States a specific verb and resource ('Get one contact by id') and the 'by id' qualifier implicitly separates it from siblings like rinkel_list_contacts and rinkel_find_contact_by_number. It stops short of naming the alternatives explicitly, so it is clear but not fully differentiated.

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 'by id' phrasing implies the precondition (you must already have a contact id), but there is no explicit statement of when to use this versus rinkel_find_contact_by_number or rinkel_list_contacts, and no mention of what happens when the id is unknown.

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 declare readOnlyHint=true, so the safety profile is already covered. The description adds genuinely useful behavioral context by spelling out exactly what the response contains, which matters since there is no output schema.

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

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

A single front-loaded sentence naming the resource and its contents, plus a short endpoint reference. No filler, and the most decision-relevant information comes first.

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 one required parameter, no output schema, and read-only annotations, the description covers what an agent needs. Enumerating the dial-plan fields compensates for the missing output schema, though it stops short of describing response shape or error behavior.

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 is documented with a pointer to rinkel_list_numbers. The description adds no additional 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 ('Get one Rinkel number') and enumerates the returned payload (dial plan, greeting, business hours, forwarding, voice menu, recording, caller-id). This clearly separates it from rinkel_list_numbers, though the sibling routing is implied 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?

Usage is implied: fetch details for a single number when you already have its id. There is no explicit when-to-use, no mention of rinkel_list_numbers as the way to obtain number_id, and no stated 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?

readOnlyHint=true already covers the safety profile, and the description adds real value on top by naming the fields returned (preferences, notification settings, schedule, deviceId) and mapping to GET /users/{id}. It omits error behavior for unknown ids and any auth/rate-limit notes.

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

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

Two short sentences, zero filler, with the return-shape information front-loaded ahead of the endpoint mapping.

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 enumerated return fields do the necessary work of telling the agent what comes back, and the required vs optional params are handled by the schema. Only failure semantics (unknown user id) and the include_avatar side effect are left unaddressed.

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

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

Schema description coverage is 100%, so both user_id and include_avatar are already documented by the schema. The description adds nothing about include_avatar's effect or whether the avatar is otherwise omitted, 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 plus the identifier semantics ('Get one user by id') and enumerates the payload fields, which cleanly distinguishes it from the sibling rinkel_list_users. It stops short of naming the sibling explicitly, so it is clear but not maximally differentiated.

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: the agent must already hold a user_id. There is no guidance such as 'use rinkel_list_users first to resolve an id' and no statement of 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.

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavior beyond them: the URL is temporary with a 3-hour validity window, it can be used to stream or download, and it maps to a specific API endpoint. Auth requirements and rate limits are not mentioned, keeping it from a 5.

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

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

Two tight sentences with the core capability and the key constraint (3-hour expiry) front-loaded. Zero 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 single-parameter read tool this is nearly complete: the id source, the purpose, the expiry, and the endpoint are all covered. A minor gap is that the return shape (field name for the URL, whether an expiry timestamp is included) isn't described, though 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 coverage is 100% and the single parameter is already documented as 'The voicemail id (`voicemail.id`)'. The description repeats and slightly extends this by noting the id comes from a call or voicemail record, but adds little 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 ('Get a temporary URL ... to stream or download a voicemail') plus scope details (3-hour validity, id source, endpoint). It doesn't explicitly differentiate itself from the near-sibling rinkel_get_call_recording_url, so it falls just short of a 5.

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

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

Usage is implied by 'stream or download a voicemail' and the id source is clarified, but there is no explicit statement of when to prefer this over rinkel_list_voicemails or rinkel_get_call_recording_url, and no when-not guidance.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful context: it returns newest-first by default, includes AI summary and sentiment only when Rinkel AI insights are available, and maps to GET /call-detail-records. It does not cover pagination behavior or authentication requirements, but those are less critical for a read-only list tool.

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 front-loaded with the core purpose, followed by concrete usage examples, default ordering, and the API endpoint. It is appropriately sized for a 24-parameter list tool and no sentence feels 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?

For a complex list tool with 24 optional filters and no output schema, the description does enough: it names the returned fields, clarifies default ordering and AI-insight conditions, and provides realistic query examples. The schema covers parameter details, though the description could have mentioned pagination or explicitly routed voicemail-specific queries to rinkel_list_voicemails.

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 input schema already documents all 24 parameters in detail. The description reinforces the kinds of data available and implies filterable dimensions such as date, direction, status, duration, and users, but it does not add syntax or constraints beyond what the schema provides.

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: it lists call detail records, both inbound and outbound, and enumerates the fields returned. It is clearly distinguishable from a single-call getter, but it does not explicitly differentiate itself from adjacent list tools such as rinkel_list_voicemails or rinkel_list_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?

It gives concrete use cases such as 'who called today', 'which calls did we miss this week', and 'calls longer than 5 minutes', which clearly indicate when to use the tool. It does not state when not to use it or name alternative sibling tools for related queries.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds useful context beyond that by disclosing the GET /contacts endpoint and flagging the non-obvious inclusion of the Rinkel system contact (tag 'system'), which an agent might otherwise mistake for user data. It stops short of stating pagination/ordering behavior, so not a 5.

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

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

Two compact sentences with no filler: scope first, returned fields second, endpoint as a trailing hint. Nothing an agent does not need.

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

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

For a read-only paginated list with no output schema, the description names the fields returned and the notable system-contact inclusion, and the schema carries paging details. Only minor gaps remain (total count, result ordering), which are unlikely to affect 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 100% and all four parameters (page, filter, letter, per_page) are documented with defaults and bounds in the schema. The description adds no extra meaning about filtering or letter 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?

A specific verb (List) plus a precisely scoped resource: contacts shared with everyone in the account, with the system contact called out explicitly. The list of returned fields (names, company, phone numbers, email) further pins down what an agent gets, and the scope wording separates it from get_contact, find_contact_by_number, and create_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?

The scope phrase 'shared with everyone in the account' implies this is the browse/enumerate operation rather than a targeted lookup, but the description never names alternatives such as rinkel_find_contact_by_number or rinkel_get_contact, nor states when not to use it. Usage is inferable, not 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?

readOnlyHint=true already covers the safety profile, so the description adds genuine value by disclosing the response shape (id, label, number, status, activation date, assigned users) and the underlying endpoint GET /numbers. It does not mention ordering, pagination or result-size behavior, which is the main remaining gap for a list tool.

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

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

Two sentences, zero filler, front-loaded with the action and resource before the field list and endpoint reference. Every clause carries information an agent can act on.

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

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

With no parameters and no output schema, the description does the heavy lifting by enumerating returned fields and status values, which is what an agent needs to decide relevance. Only pagination/ordering and total-count behavior are left 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?

The tool takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. The enumerated status values (ACTIVE, SUSPENDED, PENDING_PORTING_IN) usefully characterize the returned data even though no input 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?

States a specific verb (list) and resource (the account's Rinkel phone numbers) and enumerates the returned fields, including the status enum values. An agent can distinguish this from rinkel_get_number (single fetch) without opening any schema, since 'the account's ... numbers' signals a full collection.

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: 'List the account's ... phone numbers' tells the agent it is a collection read, but there is no explicit when-to-use instruction and no mention of the obvious alternative (rinkel_get_number for a single number) or of rinkel_list_users for the assigned-users data. Adequate but leaves routing 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?

With readOnlyHint=true already declaring the safety profile, the description adds real context: what the records represent (dial-plan audio assets), what each entry carries (name, description, duration, usage location), and the backing endpoint. It says nothing about pagination defaults or result volume, but the schema covers those.

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, both earning their place: the first defines scope and return contents, the second prevents the most likely misidentification. Front-loaded with the core verb and resource.

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 compensates by enumerating the fields each recording exposes and its usage context. Paging and sorting semantics live in the schema, so the only residual gap is behavior at scale (total counts, result caps).

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 all four optional paging/sort parameters fully described (defaults, ranges, enums), so the schema does the heavy lifting. The description adds no parameter-level meaning beyond that, which is the baseline case.

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 uploaded audio recordings used in the dial plan'), enumerates the subtypes (greetings, announcements, voice-over scripts), lists the fields returned, and gives the underlying endpoint. The explicit 'Not call recordings' line separates it from the call-recording siblings in the same namespace.

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 'Not call recordings' exclusion and the 'used in the dial plan' scoping give a clear condition for when this tool is right rather than rinkel_get_call_recording_url. It stops short of naming the alternative tool explicitly, so the agent must infer the routing rather than being handed it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that: it spells out the returned payload shape (name, email, role enum values, availability, device info) and a cross-tool dependency (deviceId required to start a call) that the agent otherwise could not infer.

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

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

Two sentences with zero filler, and the core action plus returned fields are front-loaded before the API endpoint reference. The dense field list is information the agent needs given there is no output 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?

With no output schema, the description compensates by enumerating return fields and flagging the deviceId dependency, which is enough to call it correctly. Pagination, ordering, and result-size behavior are unstated, a minor remaining gap 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?

Only one optional parameter (include_avatars) and schema description coverage is 100%, so the schema fully documents it. The description adds nothing about the parameter, but baseline 3 applies when the schema carries the load.

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 account's users') and enumerates the fields returned, which lets an agent distinguish it from the singular rinkel_get_user without opening either schema. It stops short of explicitly naming that sibling as the alternative for single-user lookups.

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

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

No explicit when-to-use/when-not guidance, but usage is implied: this is the enumeration path for users, and the parenthetical 'deviceId is needed to start a call' hints at the downstream use case (rinkel_start_call). The choice between this and rinkel_get_user 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 declare readOnlyHint=true, but the description adds real behavior: default ordering ('Newest first'), the destructive-to-filters effect of is_new, the returned fields, and the underlying endpoint. It stops short of describing pagination behavior (total counts, next page), which is the remaining gap.

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

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

Three short sentences with zero filler; the identity of the resource comes first, then the returned fields, then the ordering, then the one behavioral caveat. Every sentence carries information an agent can act on.

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

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

With 14 parameters and no output schema, the description wisely enumerates the returned fields and flags the one surprising filter interaction. Only pagination/result-envelope behavior is unaddressed, which is a minor omission for an otherwise self-sufficient definition.

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

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

Schema description coverage is 100%, so all 14 parameters are already documented, and the enum values for sort_order and date_preset live in the schema. The description reinforces only the is_new override and the default ordering, adding marginal meaning beyond structured data, 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 voicemail messages') and then disambiguates the resource by defining it as 'call records with status VOICEMAIL', which cleanly separates it from the sibling rinkel_list_calls. It also names the fields returned, so an agent knows exactly what shape of thing it is getting.

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 one explicit usage rule ('With is_new=true Rinkel ignores every other filter and returns only unplayed voicemails'), which is genuinely useful. However, it never says when to prefer this over rinkel_list_calls or rinkel_count_new_voicemails, so the choice among siblings 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds meaningful context beyond annotations: the Expert plan requirement, the event types covered, and the returned URL and active flag fields.

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

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

Two tight sentences with the core purpose front-loaded. The event list, plan requirement, and endpoint are all relevant 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 zero-parameter read-only list tool, the description is complete enough: it says what is listed, which event types are involved, what fields are returned, and the plan prerequisite. No output schema is present, but the description provides adequate return-field context.

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 there are no parameter semantics to explain. The baseline score for a zero-parameter tool is appropriate.

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

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

States a specific verb and resource: list webhook subscriptions. It enumerates the relevant event types and returned fields, and clearly distinguishes this from the sibling list tools for calls, contacts, numbers, recordings, users, and voicemails.

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 by stating that webhooks require the Expert plan, which is a useful prerequisite. It does not explicitly state when to use this versus alternatives, but no sibling tool lists webhooks.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and non-idempotent, so the write/destructive profile is covered structurally. The description's added value is the cost model (call minutes charged to the account), the ringing sequence, and caller-id visibility to the callee — genuinely useful context beyond annotations. It stops short of describing failure modes (busy, unverified device) or what the response contains, keeping this at a solid but not exceptional 3.

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 critical warning 'WRITE, COSTS CALL MINUTES' is front-loaded in caps, followed by behavior, preconditions, and sourcing guidance in a logical order. The middle sentence is a long run-on that packs several facts, slightly hurting scannability, but 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?

For a destructive, cost-incurring mutation with no output schema, the description covers preconditions, side effects, id sourcing, and the underlying API call. The main omission is the return shape (e.g., call id or status), which would help the agent chain into rinkel_get_call.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real meaning on top: it explains the origin endpoint for device_id and number_id and repeats the gating semantics of confirm in prose. The two-stage ring-then-dial behavior also clarifies what device_id actually controls (which endpoint rings first).

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 a specific verb+resource ('starts a real phone call') and precisely describes the two-stage dialing model: Rinkel rings the user's device first, then dials `to` with the chosen number as caller id. This is unmistakable against all read-only siblings like rinkel_list_calls or rinkel_get_call.

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

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

Explicitly states the precondition (confirm=true, set only after the user explicitly asked to place this call) and tells the agent exactly where to source the two id parameters (device_id from rinkel_list_users, number_id from rinkel_list_numbers). It also flags the cost consequence so the agent can decide whether to invoke at all.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered, and the description's 'WRITE:' prefix is consistent with them. It adds real context beyond the annotations: the exact-match requirement for wildcard entries and the underlying DELETE endpoint. It does not say how a non-blocked or malformed entry is handled, which is the remaining gap.

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

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

Two short sentences with the write semantics and the matching constraint front-loaded and the API endpoint as trailing reference. Nothing is redundant with 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?

For a one-parameter idempotent write with full schema coverage, annotations and no output schema, the description covers purpose, exact-match behavior and the endpoint. Missing only the failure case (number not currently blocked), which is a minor gap given the annotations.

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

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

Schema coverage is 100% and the schema already says 'the blocked entry exactly as it was blocked', so the baseline is 3. The description earns the extra point by clarifying that the value may be either a plain number or the wildcard pattern that was originally blocked, which is not obvious from the parameter name alone.

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 plus resource ('remove a number from the block list'), with the effect on behavior ('so it can call again') and the underlying API call (DELETE /privacy/unblock-number) stated explicitly. The 'WRITE:' prefix and the 'unblock' framing cleanly separate it from the sibling rinkel_block_number without needing its 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?

The description makes the use case unambiguous: undo an existing block so the number can call again, and it warns that wildcard patterns must be supplied exactly as blocked. It never names rinkel_block_number as the counterpart or states what happens if the entry is not blocked, so it stops short of full when/when-not guidance.

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

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

The 'WRITE:' prefix and 'replace the text' wording make concrete why destructiveHint=true — the prior note text is overwritten — which is real context beyond the bare annotation flags. It also discloses the underlying PATCH endpoint. It stops short of stating error behavior for a missing note id or permission requirements.

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, operation type front-loaded in a scannable 'WRITE:' tag, followed by the endpoint. No filler, and the most decision-relevant detail (replace vs create) comes first.

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

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

For a 3-required-parameter mutation with no output schema, the definition covers what is mutated, where the ids come from, and the API path. What is missing is failure-mode behavior (nonexistent note id), whether the note's timestamp changes, and any auth scoping — minor but real gaps.

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

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

With 100% schema description coverage, the schema already documents all three parameters including the `notes[].id` provenance for note_id. The description only restates that mapping and maps names to path segments (callId, noteId), adding marginal semantics — the baseline 3 applies.

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

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

The description pairs the specific verb 'replace' with the resource 'the text of an existing note on a call record', and the 'existing note' qualifier separates it from rinkel_add_call_note and rinkel_delete_call_note. An agent can pick this tool over its note-related siblings without opening any schema.

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

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

Usage is implied rather than stated: 'existing note' rules out creation, and the pointer to `notes[].id` tells the agent where to find the required id. However, no alternative is named explicitly (e.g. use rinkel_add_call_note to create, rinkel_delete_call_note to remove), so routing still requires inference from the sibling list.

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

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

Beyond the destructiveHint annotation, the description spells out exactly what is destructive: numbers are replaced wholesale, an omitted default_outbound_number_id clears it, while omitted names/company/email keep stored values. This is precisely the behavioral context an agent needs for a PUT-style update.

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 dense but front-loaded: operation type and semantics first, then required replacement behavior, then omission rules, then the read-first instruction and endpoint. Every sentence carries necessary information.

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

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

With no output schema, the description still gives enough behavioral detail for safe invocation: required fields, replacement semantics, omission behavior, immutability of the system contact, and a prescriptive read-before-write workflow.

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

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

Schema description coverage is only 43%, but the description compensates by explaining that numbers is required and replaces all stored numbers, and that omitted default_outbound_number_id clears it whereas other omitted fields retain their value. This adds critical semantics not fully captured in 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 states a specific write operation (update a contact) with PUT semantics and endpoint, clearly distinguishing it from read tools like rinkel_get_contact and from create/delete siblings. An agent can immediately tell this is a mutation 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 explicitly instructs the agent to read the contact first via the named sibling rinkel_get_contact and resend what must stay. It also states the system contact cannot be changed, giving a concrete exclusion.

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

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

Annotations already declare readOnlyHint=true, and the description is consistent with that. It adds real behavioral context beyond the annotations — normalisation of the input and an optional availability lookup — but does not say what happens on an invalid number (error vs. a validity flag) or what the response shape is beyond 'normalised form'.

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 no waste; the core purpose is front-loaded and the optional flag and API endpoint follow in descending order of importance.

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

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

For a read-only validator with a fully described three-parameter schema and no output schema, the description covers purpose, the optional inventory mode, and the endpoint. Only the outcome when validation fails and the exact result fields 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 coverage is 100%, so all three parameters are already documented in the schema, including 'number without the country calling code'. The description only echoes check_inventory's meaning and adds the notion of a normalised output, 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 — check/normalise a phone number for a given country — which is clearly distinct from rinkel_get_number (retrieve a stored number) and rinkel_find_contact_by_number. It does not explicitly name those siblings, but the operation is unambiguous from the sentence and 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 conditional 'With check_inventory=true Rinkel also checks whether the number is available to order' implies when to flip that flag, but there is no explicit when-to-use guidance versus siblings such as rinkel_get_number or rinkel_block_number, and no stated exclusions or prerequisites.

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