myPhoner MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds genuinely new behavior — the lead moves to that state, an event is logged on it, and no notification is sent to the lead. That last point is important context an agent could not derive from the schema. It stops short of addressing re-archiving or whether the action is reversible.

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 that front-load the effect and its side effects, followed by the HTTP route. Every clause adds information; the endpoint path is mildly redundant but cheap.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers the important ground: what state the lead enters, that an event is recorded, and that no outbound message is sent. The unexplained callback parameters are the main remaining gap.

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

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

Schema coverage is 100%, so the four optional parameters are already documented, establishing a baseline of 3. The description reinforces the comment and category ("existing archive category") but says nothing about call_back_in or scheduled_for, leaving an agent to wonder why a callback would accompany an archive.

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 ("Archive a lead") and immediately defines the operational effect — the lead leaves the calling queue — which no sibling name conveys. It does not explicitly differentiate itself from close cousins like myphoner_mark_lead_loser or myphoner_move_lead, but an agent can infer the distinction from the state-change wording.

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 described effect (removal from the calling queue) rather than stated as a when-to-use rule. There is no guidance on when to archive versus marking a lead loser or moving it, and no prerequisites or caveats about archiving an already-archived lead despite idempotentHint=false.

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

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

Annotations already declare the mutation profile (readOnly=false, idempotent=false, destructive=false), so the bar is lower, yet the description adds a genuinely non-obvious trait: duplicate detection runs asynchronously minutes later, and the caller must re-read detected_duplicates. It omits what happens on validation failure or whether retries create extra leads.

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

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

Four short sentences, front-loaded with the core action, then ordering caveat, then the dedup caveat, then the endpoint. Every sentence carries information the agent needs; nothing is 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 create tool with no output schema, the key operational facts (where column keys come from, deferred dedup, no outbound message) are all present. Minor gap: it never states what is returned (presumably the created lead) or which columns are required by a given list.

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 are documented in-schema, so baseline 3 applies. The description's note that `fields` keys are list column keys largely repeats the schema's own wording, adding no syntax or type guidance for the nested object beyond what's already given.

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 ("Add a new lead to a list") plus the REST endpoint, which makes it unambiguously distinct from myphoner_update_lead, myphoner_create_list, and myphoner_move_lead. An agent can select it 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?

Points at the prerequisite sibling (myphoner_list_columns) for obtaining valid column keys, and the line "Creates data only; nothing is sent to the lead" separates it from outreach-style siblings like delegate_lead. It stops short of an explicit "use update_lead instead when the lead already exists" 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?

Goes beyond the annotations by stating the side effect precisely: 'Creates data in the account (nothing is sent to anyone),' which usefully disambiguates the openWorldHint=true flag for a create operation. It stops short of covering non-idempotency consequences (calling twice likely yields two lists with the same name) or any 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?

Front-loaded with the core action and scope, then side effects, then field kinds — ordered by importance. Tight overall; the trailing 'POST /lists' is a minor implementation detail that doesn't help an agent decide or call 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?

For an 8-parameter create tool with no output schema, the description covers purpose, side effects, and field kinds well, but never says what comes back (e.g., the new list's identifier needed for subsequent lead operations) or what defaults apply when columns is omitted — the latter is only hinted in the schema.

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

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

Schema description coverage is 100%, so the schema already documents name, columns, the category strings, and the field-kind enum, making 3 the baseline. The description's recital of field kinds and 'none (text)' / 'text (multi-line)' clarifications largely restates the enum documentation rather than adding new meaning.

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 + scope: 'Create a new, empty calling list with its fields,' which clearly separates it from siblings like myphoner_create_lead, myphoner_list_lists, and myphoner_get_list. 'Empty' is a meaningful qualifier telling the agent no leads are added here.

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 tool creates a list, so it presumably precedes lead creation/moves, but the description never says when to call this versus myphoner_create_lead or how it relates to an existing list retrieved via myphoner_get_list. No exclusions or prerequisites (e.g., name uniqueness) 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 destructiveHint=true, idempotentHint=true, openWorldHint=true and readOnlyHint=false, so the mutation/safety profile is known structurally. The description adds useful behavioral context — the lead lands in the target agent's queue — but does not say what happens to the previous owner's claim, whether the previous owner is notified, or what authorization is required for a destructive reassignment.

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

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

Two short sentences, front-loaded with the action and its effect; nothing is padded. The trailing 'PATCH /leads/{id}/delegate' is marginally useful implementation detail but earns little for an agent choosing a 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?

For a two-parameter mutation with full schema coverage and rich annotations, the description covers the action and its user-visible consequence, which is close to sufficient. Gaps remain: the 'claim' case mentioned in the title is never explained, and the impact on the current owner of the lead is unstated.

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

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

Schema description coverage is 100%, so both lead_id and delegate_to are documented in the schema itself. The description's 'identified by user id or email' merely restates the delegate_to schema description and adds no format, constraint, or edge-case detail 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?

The description names a specific verb+resource ('Give the claim on a lead to a user') and states the observable effect (the lead appears in that agent's queue), which is more than the title alone provides. It does not, however, distinguish this from siblings like myphoner_move_lead or myphoner_update_lead, nor does it explain the 'claim' half of the title (delegating to oneself).

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 tool for reassigning lead ownership, but there is no explicit when-to-use guidance, no mention of when to prefer move_lead or update_lead, and no prerequisites or exclusions stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds exact-match semantics and the endpoint shape, but it does not explain what happens on no match, how many results are returned, or any pagination 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?

It is three compact sentences with the exact-match behavior and the key use case front-loaded. The endpoint reference is secondary and does not bury the 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?

There is no output schema, so the description should ideally clarify what a successful find returns, such as matching lead objects or an empty result. It covers the input behavior and safety context adequately but leaves a meaningful gap around return values and no-match 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 coverage is 100%, so the schema already documents fields, list_id, and match_all in detail. The description reinforces that fields are exact-match keys and restates the match_all rule, but adds little beyond the schema's own parameter descriptions.

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

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

The description states a specific operation: exact-match lookup on one or more fields of a list, with examples such as phone number or email. It distinguishes itself reasonably from broader retrieval tools like myphoner_list_leads or myphoner_search_leads by specifying 'exact match,' though it does not name those siblings directly.

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

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

It gives a concrete usage scenario, checking whether a lead already exists, but does not say when to prefer this over myphoner_search_leads or myphoner_list_leads. The guidance is implied rather than explicit about alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful semantics beyond that: it discloses the returned field set and interpretation rules such as 'duration (0 = unanswered)' and the disposition vocabulary (normal, voicemail, no_answer, busy ...). It doesn't mention error behavior or pagination/expansion options, but for a safe single-record read that is minor.

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 clause that enumerates the payload fields, followed by the endpoint. Every element earns its place and there is no filler or 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 burden of describing the return value, and it does so by listing the returned fields and edge-case semantics. What's missing is only peripheral: error/not-found behavior and whether 'recording links' require additional access. For a one-parameter read tool this is close to 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 schema itself explains that call_id is 'the number at the end of a call's location path'. The description adds no further parameter meaning, so the baseline of 3 applies — the schema does the heavy lifting here.

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

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

The description names the resource ('One call made from myPhoner') and enumerates the fields it returns, with 'GET /calls/{id}' confirming this is a single-call fetch by id. It's clearly distinguishable from sibling tools, which are all lead/list operations. It stops short of an explicit retrieval verb like 'Fetch one call by id', but the intent is unambiguous.

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

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

Usage is implied by the path template GET /calls/{id} and the required call_id, so an agent can infer this is the way to look up a single known call. However, there is no explicit statement of when to use this versus e.g. myphoner_get_lead or myphoner_list_columns, and no note on what happens when the id doesn't exist.

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 earns credit by disclosing the payload shape ('state, category, claim, duplicates and all lead_data fields'), which is the only return-value information available since there is no output schema; it stops short of stating behavior for a missing or inaccessible lead.

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 filler: the returned content comes first and the endpoint qualifier second. Every clause carries information.

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

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

For a one-parameter read tool with annotations covering safety, the definition supplies what the schema cannot: the returned fields, partially compensating for the absent output schema. Only the not-found/error behavior and the source of a valid lead_id 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?

Only one parameter exists and schema description coverage is 100%, so the schema alone documents lead_id as a positive integer. The description adds nothing about the identifier's format or origin, which is the baseline expectation when the schema is fully covered.

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

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

The description names a single resource ('One lead'), enumerates the returned sub-resources (state, category, claim, duplicates, lead_data), and pins it with the endpoint GET /leads/{id}. This makes it clearly the single-lead fetch as opposed to the list/search siblings, though the verb 'retrieve' is only implied by the endpoint string.

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 versus myphoner_find_leads, myphoner_search_leads, or myphoner_list_leads, nor any prerequisite (e.g. that an id must come from one of those tools). The agent must infer the selection rule from the name 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the description only needs to add context. It does add the payload contents (lead count plus the five category buckets), which is useful for a tool with no output schema, but says nothing about permission requirements, 404/not-found behavior, or response shape beyond that enumeration.

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 filler: the returned content is front-loaded and the endpoint is appended as a compact disambiguator. Nothing repeats the title or restates 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?

With no output schema, the description carries the burden of describing what comes back; it names the lead count and the category buckets but leaves the rest of the list object (name, columns, metadata) unspecified. For a simple by-id read with full annotation coverage this is workable but not complete.

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

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

The single list_id parameter is fully documented in the schema, including its provenance from myphoner_list_lists and its positive-integer bound. The description adds only the endpoint mapping 'GET /lists/{id}' and no additional format or constraint detail, 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 gives a specific verb-resource pair: fetching 'one calling list' with its lead count and the call back/winner/loser/archive/skip category breakdowns. 'One' implicitly contrasts with the plural listing sibling myphoner_list_lists, so an agent can distinguish them, though the sibling is never named.

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

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

Usage is only implied by the singular 'one calling list' and the 'GET /lists/{id}' endpoint, which signals a by-id single-resource fetch rather than a search or list. There is no explicit when-to-use, no prerequisites, and no named alternative such as myphoner_list_lists or myphoner_get_list_stats.

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 aggregation semantics (counts grouped by state and category, not raw leads) and the underlying GET endpoint, but says nothing about cost, latency, or whether empty states are omitted. Some added value, not rich context.

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: what it returns, when to use it, and the endpoint. The return-shape detail is front-loaded and every sentence carries information.

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

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

With no output schema, the description correctly compensates by enumerating the state buckets and mentioning category breakdowns. Minor gaps remain (whether zero-count states appear, or whether categories are user-defined), but an agent can call this confidently.

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

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

Only one parameter (list_id) and schema coverage is 100%, so the schema fully documents it. The description adds nothing about list_id beyond implying it scopes the stats; the baseline 3 applies when the schema does all 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?

The description states the resource (lead counts of a list) and the exact breakdown returned (state buckets plus category within each state), which is far more specific than the bare title. It is clearly distinct from siblings like myphoner_get_list or myphoner_list_leads, though it doesn't explicitly name them as alternatives.

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 it for campaign progress and conversion questions" gives concrete task contexts that select this tool over the raw list/lead endpoints. There are no exclusions or negative guidance (e.g., when to prefer myphoner_list_leads instead), so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP endpoint (GET /lists/{id}/columns) and the semantic meaning of the returned keys, but says nothing about what happens for an invalid or missing list 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 and an endpoint reference with no filler; the payload semantics (what `key` means) are front-loaded where the agent will read them.

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 no output schema, the description covers the essentials: what is returned (fields/columns), the identity of each item (`key`), and how that identity is used downstream. It stops short of describing the other attributes each column object may carry.

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 parameter exists and schema coverage is 100%, with the schema documenting `list_id` as a positive integer list id. The description's `{id}` in the endpoint path loosely corroborates it but adds no new 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?

The title-plus-description pair states a specific resource ("the fields (columns) of a list") and the endpoint confirms it is a read of list column metadata. It is distinguishable from siblings like get_list or list_lists, though the description itself is a noun phrase and leans on the title for the verb.

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 second sentence gives a concrete use case: the returned `key` values are what you must use when creating, updating or finding leads, which tells an agent to call this before write operations. No explicit exclusions or named alternatives are given, keeping it below a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuinely useful context beyond them: the default sort order, the alternative order, and the shape of returned records including state values (new, call_back, won, lost, archived), category, scheduled call back, claimant, and lead_data. It stops short of 5 because it doesn't describe pagination behavior or the total/next_page semantics of the reply.

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 ordering front-loaded and no filler; the field inventory is compact. The trailing 'GET /lists/{id}/leads' is mild redundancy with the name and annotations but still reinforces the read semantics in few characters.

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 compensates by enumerating the returned lead fields and the possible state values, and it documents the two ordering modes. Pagination behavior (page/per_page, next_page) is left entirely to the schema, which is acceptable given its 100% coverage but is the one remaining gap for a paged list endpoint.

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 list_id, page, per_page, and the order enum are all already documented in the schema, including defaults and the next_page handoff. The description only restates the order semantics, adding no syntax or format detail beyond the structured fields, 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 its scope precisely: leads belonging to one list, with explicit default ordering and the order=last_updated_first alternative, plus the fields each lead carries. The verb is implicit (no 'list/return' verb, only the trailing GET endpoint), and it does not distinguish itself from siblings like myphoner_find_leads or myphoner_search_leads, so it stops short of a 5.

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

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

Usage is implied: it requires a list_id and returns that list's leads, so an agent can infer it is the correct tool when the list is already known. However, there is no explicit statement of when to prefer it over find_leads/search_leads (e.g., 'no filtering by user/state; use search_leads for that'), 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 safety is covered without description effort. The description adds genuine value by disclosing the returned field set (id, name, creation date, lead count, defaults guarantee), which compensates for the absent output schema. It says nothing about pagination or result limits, which is the remaining gap for an open-world list 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?

Two compact sentences with the payload description front-loaded and the usage hint second; the "GET /lists" endpoint tag is a cheap, useful anchor. 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 read-only list tool with no output schema, the description covers both what is returned and when to call it, which is nearly all an agent needs. Pagination/ordering behavior for an open-world endpoint is the one thing left unstated.

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

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

There is a single optional parameter with 100% schema description coverage, so the schema already carries the meaning. The description echoes the concept ("whether the list guarantees the default fields") but describes it as returned data rather than as a filter, adding no syntax 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 and resource ("All calling lists (campaigns) in the account") and enumerates the fields returned, so an agent knows exactly what comes back. It also points to its position relative to detail-fetching siblings with "Start here to find a list id," distinguishing it from myphoner_get_list and myphoner_list_leads.

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?

"Start here to find a list id" gives a clear entry-point condition, implicitly routing agents to get_list for detail. It does not explicitly name the alternative tools or their exclusions, which keeps it short of a 5.

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

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

Goes beyond the annotations by disclosing that the lead's state changes, that an event is logged on the lead, and crucially that 'nothing is sent to the lead' — an important side-effect clarification the destructiveHint annotation alone doesn't convey. It also names the endpoint. It does not cover reversibility or permission requirements, which matters for a destructive mutation.

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

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

Three tight sentences, front-loaded with the action, then the side effects, then the parameters and endpoint. No filler or redundancy.

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

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

For a state-changing tool with no output schema, it covers what happens to the lead, what is recorded, and what is not sent. A brief note on whether an existing call back can be overwritten or cancelled would make 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 coverage is 100%, so the baseline is 3. The description restates the call_back_in versus scheduled_for choice and mentions the optional comment and category, but adds no meaning beyond what the schema's own descriptions already provide.

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 ('Schedule a lead for a call back') and clarifies the resulting state change and event logging. It is clearly distinct from winner/loser/archive siblings in substance, though it never names an alternative 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 scheduling intent is implied by the description and the 'Set when with call_back_in (minutes) or scheduled_for' line gives practical guidance on choosing between the two timing parameters. However, there is no explicit statement of when to use this versus mark_lead_winner, mark_lead_loser, or delegate_lead.

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=false, but the description adds real value beyond them: the lead enters the loser state, an event is logged for audit, and no notification is sent to the lead. It does not address reversibility or whether re-running on an already-lost lead errors, which matters given idempotentHint=false.

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-load the state change, then side effects, then options. The trailing endpoint reference is cheap and unambiguous; 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 mutation with no output schema, the description covers the key facts: state change, event logging, no outbound message, and optional comment/category. It omits any mention of the scheduling parameters that exist in the schema and does not say what the call returns, both minor given the fully documented schema and 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 description coverage is 100%, so the baseline is 3. The description only echoes two of the five parameters (comment, category) and adds a small clarification that the category must already exist; it says nothing about call_back_in or scheduled_for, leaving the agent to rely entirely on schema descriptions.

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

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

States a specific verb and resource ('Mark a lead as a loser') and immediately disambiguates the term with '(not interested / lost)'. Combined with the sibling name mark_lead_winner, an agent can tell exactly which state transition this performs 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 parenthetical '(not interested / lost)' plus 'nothing is sent to the lead' gives clear context for when this is the right transition rather than a winner/callback mark. It stops short of an explicit exclusion (e.g. use mark_lead_winner instead when the deal closed successfully), so no true 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?

Goes beyond the annotations by disclosing concrete side effects: the lead transitions to the won state, an event is logged on the lead, and 'nothing is sent to the lead' (important reassurance for a destructiveHint=true tool). It does not address reversibility or whether the previous state is recoverable, which is a notable gap for a destructive, non-idempotent operation.

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

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

Three short sentences, front-loaded with the action and its effect, followed by the side-effect clarification and the optional inputs. No filler and the endpoint path is tacked on at the end without disrupting flow.

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, a destructive non-idempotent mutation and a fully-described schema, the description supplies the essential behavioral picture. It falls short only on return value expectations and on acknowledging the two scheduling parameters, which an agent might otherwise miss.

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 five parameters are already documented, making 3 the baseline. The description adds only that comment and category are optional and that the category must already exist, while omitting mention of call_back_in and scheduled_for entirely.

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 ('Mark a lead as a winner') plus a parenthetical clarifying the business meaning ('a won deal'), so the outcome is unambiguous. Against siblings like mark_lead_loser and mark_lead_call_back, the target state is clearly differentiated by the word 'winner'.

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

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

The description implies the usage context (a deal was won) but never says when to prefer this over mark_lead_loser or update_lead, nor does it state preconditions such as 'the lead must be in an open state'. Usage is inferable 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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the non-obvious nuance that a same-list call doubles as a claim release, which tempers the destructive framing in that one case. It does not state what a normal move does to the lead's claim, history, or callbacks on the source list, so it adds only partial behavioral context.

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

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

Three short sentences, front-loaded with the action and immediately followed by the one case an agent would otherwise get wrong. The trailing endpoint string is marginally useful but not essential 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 3-parameter mutation with no output schema, the description plus annotations cover the essentials: what it does, the destructive and idempotent nature, and the release edge case. Remaining gaps (error conditions, whether a claim is required) are modest.

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 both required ids and release_claim are already documented, establishing a baseline of 3. The description earns the extra point by explaining the interaction between release_claim and a same-list destination, which the schema does not capture.

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

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

The description uses a specific verb and resource ('Move a lead to another list') and adds the raw endpoint (PATCH /leads/{id}/migrate), so the action is unambiguous. It does not distinguish this from siblings like myphoner_delegate_lead, myphoner_update_lead or myphoner_archive_lead, which also touch lead state.

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

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

It gives a genuinely useful conditional: if the destination equals the lead's current list, release_claim=true makes the call a claim release rather than a relocation. That tells the agent when this tool is the right one for de-claiming. It stops short of naming alternatives for the move-vs-update-vs-archive decision.

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. The description adds useful context beyond that: it searches activity logs including comments and events, and returns a total hit count plus one page of leads.

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 that front-load the core search behavior and include the return shape and endpoint with 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?

With full schema coverage and annotations covering safety, the description supplies the essential behavioral and return-shape context. It could be stronger only by explicitly differentiating this from find_leads.

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 defines query, page, per_page and list_ids in detail. The description only reinforces list scoping and pagination at a high level, which is appropriate but adds little beyond the schema.

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

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

States a specific verb and resource: free-text search across lead data and activity logs, with optional list scoping. It clearly conveys the search behavior, but does not distinguish itself from the sibling find_leads 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?

The 'like the search box in myPhoner' analogy and optional list limitation imply when to use it, but there is no explicit guidance on when to choose this over find_leads or list_leads.

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; the description adds genuinely useful context on top by explaining that only supplied fields change and that omitted fields are preserved, plus how clearing works. It does not cover auth requirements or what the response contains, which keeps it below 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 short, information-dense sentences with no filler; the core behavior (partial update) is front-loaded and the API path is a compact trailing anchor for agents mapping to endpoints.

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 nested-object mutation with no output schema, the definition covers merge semantics, clearing, and where keys come from—enough to call it correctly. It omits any indication of what a successful update returns or how invalid column keys are handled, which is the only 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?

Schema coverage is 100%, so the baseline is 3; the description earns more by stating the merge semantics of 'fields' (only passed keys are written) and the null-to-clear convention, neither of which is explicit in the schema. The column-key guidance restates the schema and lead_id is left unaddressed.

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 ('Change field values of an existing lead') and immediately clarifies scope with the partial-update parenthetical 'only the fields you pass change', which separates it from myphoner_create_lead and the mark_* tools. The HTTP verb/path tail confirms it is a PATCH-style update.

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 actionable context: keys come from myphoner_list_columns, null clears a field, and existing values are overwritten. It does not state explicit exclusions (e.g. when to prefer mark_lead_winner or move_lead over raw field edits), so it stops short of the when/when-not bar.

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