WhatConverts MCP by usefulapi

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), it discloses real side effects: the lead appears in reports and counts toward lead totals. The 'send_notification is always off, so no emails go out' detail is genuinely non-obvious behavior not derivable from any structured field, and it elaborates the non-idempotency annotation with the concrete consequence of duplicate leads. Missing rate limits, but the annotation bar is already met.

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 'WRITE' marker and the purpose, with no filler. The agency/profile sentence and the endpoint hint are dense but each carries information; nothing is padded.

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

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

For a 24-parameter, nested-object mutation tool with no output schema and no annotations covering side effects, the description covers the high-value operational facts (key scoping, no notifications, non-idempotency) but never explains which fields pair with which lead_type beyond a couple of schema-level notes, nor what the response contains. Adequate but with clear gaps.

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

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

Schema description coverage is 67%, so the schema carries most parameter meaning. The only parameter the description touches is profile_id, and it merely restates the schema's own note about Agency vs Profile keys, adding no syntax or format detail. With 24 parameters, many of them lead_type-conditional, the description leaves most semantics to 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 ('WRITE: add a lead to WhatConverts') and immediately grounds it with concrete examples (offline phone call, form submission from another system, sale). Against siblings like get_lead, list_leads and update_lead, the 'add'/'WRITE' framing makes the create-vs-read-vs-update distinction 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?

Gives clear trigger contexts for when this tool is the right choice (offline leads, externally sourced forms, offline-attributed sales) and states a prerequisite - a Profile key adds to its own profile, an Agency key must pass profile_id. It stops short of naming the alternative for existing leads (update_lead), so it's contextually clear but not exclusionary.

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 two things beyond that: the agency-key authentication requirement and the fact that the payload includes nested profiles, which is useful behavioral context for a single-account read.

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 telegraphic clauses with the auth constraint and the resource scope front-loaded; nothing is wasted. The fragment style ('Agency key only') is terse but readable and appropriately sized for a one-parameter tool.

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

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

For a single-parameter read with annotations covering safety and no output schema, the description supplies the essential facts: what is returned (one account plus its profiles) and the credential requirement. Slightly more detail on the returned profile structure would make it fully self-contained.

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% for the single account_id parameter, so the schema already documents it. The phrase 'by id' adds no syntax, format, or constraint detail beyond what the schema's integer description provides, making baseline 3 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 names a specific verb and resource ('one account by id') and adds response scope ('with its profiles'), which distinguishes it from list_accounts and from get_profile/get_user. It stops short of explicitly naming the sibling alternatives, so it is clear but not maximally differentiating.

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?

'Agency key only' is a real precondition that tells the agent when this call is viable and implies a different path is needed with non-agency credentials. No explicit when-not statement or named alternative is given, but the auth constraint provides usable context.

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

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

Annotations already declare read-only and non-destructive, so the bar is low. The description adds real value: it states the response is links and text, never audio, and pins the backing endpoint (GET /leads/{lead_id}), disclosing the data source and the shape of the return.

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?

Content is front-loaded with the returned fields first, then the audio caveat, then the endpoint provenance. Dense but every clause carries information; the parenthetical about the audio endpoint is slightly tangential but justified.

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

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

With no output schema, the description carries the burden of describing return values, and it enumerates the returned fields (links, duration, answer status, numbers, transcripts) explicitly. For a single-parameter read tool, nothing an agent needs is missing.

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

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

Schema description coverage is 100% with a single self-documented lead_id parameter, so the schema does the heavy lifting. The description adds no lead_id format or constraint details beyond it, matching the baseline for fully covered params.

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 (get) plus resource (call recording info) and a full enumeration of what it exposes: recording/voicemail links, duration, answer status, tracking/caller numbers, transcripts. It also distinguishes itself from the sibling get_lead by scoping to recording/voicemail facts, so an agent can route without opening schemas.

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 clarifies the audio boundary ('returns links and text only, never audio') and notes the raw MP3 endpoint is not used, which steers the agent away from expecting audio. It stops short of naming a sibling tool or explicitly saying when to prefer get_lead instead, so it lacks full alternative routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the field inventory of the response, which is genuinely useful given there is no output schema, but it omits auth requirements, rate limits, and the Elite-plan caveat on customer_journey mentioned in the schema.

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

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

Two sentences, front-loaded with the core purpose, with the endpoint tacked on as a compact identifier. The long field enumeration is dense but each item is informative for a schema-less response, so nearly every word earns its place.

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

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

For a single-record read whose annotations carry the safety profile and whose 100%-covered schema documents both params, the description closes the main gap by enumerating returned fields in the absence of an output schema. Missing only error/not-found behavior and the plan-tier caveat needed to call it fully correctly.

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

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

Schema description coverage is 100%, so both parameters (lead_id, customer_journey) are already documented with format and provenance. The description adds only the field-list framing and no per-parameter syntax or behavior 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 (get) and resource (a single lead by id) and explicitly enumerates the breadth of returned fields, which cleanly separates it from whatconverts_list_leads. An agent can pick this over the list sibling without opening either schema.

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

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

The description never says when to use this tool versus whatconverts_list_leads or whatconverts_update_lead, and offers no prerequisites or exclusions. The only routing hint (lead_id sourced from whatconverts_list_leads) lives in the schema, not the description.

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 safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely new behavioral context: it requires an agency key specifically, and it discloses the shape of the returned record (name, date created).

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?

Extremely compact and front-loaded: the auth constraint and scope come first, followed by return fields and the raw endpoint. The endpoint path is slightly redundant with the schema's path parameters, but nothing is wasteful.

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

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

With no output schema, the description compensates by naming the returned fields, and it notes the auth requirement. For a simple two-param read this is nearly sufficient; only the failure behavior for an unknown id is absent.

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 account_id and profile_id are already documented in the schema. The description adds no syntax, format, or constraint detail beyond what structured fields provide; baseline 3 applies.

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

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

States a specific verb and resource: 'one profile by id', which distinguishes it from the sibling whatconverts_list_profiles by making the singular/plural scope explicit. The intended return fields (name, date created) are named. It stops short of a full verb+resource sentence but 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?

'Agency key only' gives one precondition, so the agent knows this requires agency-level credentials. However, it never states when to prefer this over whatconverts_list_profiles or what happens if the id is unknown; usage is only implied by the singular scope.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: the Agency-key auth requirement and the shape/semantics of the returned data (permission levels none/view/edit per area), which the annotations cannot convey.

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

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

One compact sentence plus a REST path reference, with the access precondition front-loaded. Every element earns its place and nothing is padded.

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

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

For a single-parameter read tool with no output schema, the description supplies both the auth precondition and a summary of the return structure (per-area permission levels), which is close to sufficient. It does not name the sibling list tool as an alternative, leaving a small routing 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 description coverage is 100%, so role_id is fully documented in the schema itself. The description only echoes the identifier via the REST path 'GET /roles/{role_id}' and adds no format or constraint detail beyond what the schema already provides; 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 role') and the exact payload ('its permission levels (none/view/edit) per area'), which cleanly separates it from the sibling whatconverts_list_roles. The 'one role' framing makes the singular-vs-list distinction explicit without needing to open either schema.

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

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

'Agency key only' gives a clear precondition for when this tool is invocable, which is real usage guidance beyond the annotations. It stops short of naming an alternative (e.g. list_roles) or stating when not to use it, so it is clear context but not a full when/when-not rule.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower; the description still adds the non-obvious auth constraint ('agency key only') and the shape of the payload, including the conditional disclosure that account lists are only returned for account users. That conditional return behavior is genuine context beyond the annotations, though pagination/error behavior is unaddressed.

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 clauses plus the endpoint path; the credential gate is front-loaded and nothing is padded or repeated. Every phrase 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 single-resource GET with no output schema, the description compensates by naming the returned fields and the account-user conditional. Only marginal gaps remain (no error/not-found behavior, no note on what happens with a non-agency key).

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?

One parameter at 100% schema description coverage, so the schema already documents user_id as a positive WhatConverts user id. The description repeats the id concept implicitly ('by id') without adding format, source, or lookup guidance, 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?

States a specific verb+resource+cardinality ('get one user by id') and enumerates what comes back (role, notification settings, accessible accounts). This cleanly distinguishes it from the sibling whatconverts_list_users without the agent needing to open 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?

'Agency key only' gives a concrete precondition that determines when this tool is callable, which is real usage context rather than restated purpose. It does not name an alternative or an explicit when-not case, but the singular-vs-list split with whatconverts_list_users is inferable.

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

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

The annotations already mark this as read-only, open-world, and non-destructive. The description adds meaningful behavior beyond that: it requires an agency key and explains the non-obvious default date filtering that can otherwise hide accounts. It does not cover rate limits or response pagination, but those are partly handled by the schema.

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

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

The description is front-loaded and compact, with no wasted sentences. It delivers the prerequisite, the returned fields, the downstream use case, the date caveat, and the endpoint efficiently.

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

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

Given the simple list operation, rich input schema, and lack of an output schema, the description is complete enough. It covers authentication scope, returned profile fields, intended use of ids, and a critical date-filtering caveat.

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 high-value semantics for start_date/end_date that the schema does not fully convey: WhatConverts defaults start_date to today, so an early date is required to see all accounts.

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 and resource: list accounts (clients) of the agency, including profile fields. It is clearly a list operation, but it does not explicitly distinguish itself from sibling tools such as whatconverts_get_account or whatconverts_list_profiles.

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

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

It states the agency-key prerequisite and a concrete use case: the returned ids are used to filter leads. It also warns that start_date defaults to today, so an early start_date is needed to list everything. It lacks an explicit statement of when not to use the tool or which sibling to use instead.

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

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

Annotations already declare readOnly/non-destructive/openWorld, so the description's added value is the API's quirks: the default-to-today behavior without start_date and the hard 400-day range limit. It also discloses the permission model (Profile key vs Agency key scoping), though it says nothing about rate limits or result volumes.

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, front-loaded sentences with no filler — resource first, then the hard constraint, then the auth scoping nuance. Slight duplication: enumerating lead types restates the lead_type enum already in the schema, and the trailing 'GET /leads' is decorative.

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 23-parameter, no-output-schema list tool, the description covers the two things an agent could get wrong (missing start_date, over-long ranges) and the key-scoping rule. Pagination behavior is handled by the schema's next_page/per_page descriptions, so the remaining gap is minor.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning on top: why start_date is required, the 400-day interaction between start_date and end_date, and the authorization semantics of account_id/profile_id. That exceeds what the schema's per-field descriptions convey.

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) plus resource (tracked leads), enumerates the lead types returned, and summarizes the payload (attribution, contact details, values, transcripts). This clearly separates it from siblings like whatconverts_get_lead (single lead) and whatconverts_create_lead.

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 concrete invocation context: start_date is mandatory because the API otherwise defaults to today, ranges are capped at 400 days, and key type determines whether account_id/profile_id narrowing is available. It never names an alternative sibling verb, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the read-only listing endpoint, the key-type-dependent visibility scope, and the shape of the payload. It omits ordering, default page cursor semantics and whether inactive numbers are returned, keeping it out of 5 territory.

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

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

One compact paragraph: the returned-field inventory comes first, the key-scoping rule second, the endpoint last. No filler, no repetition of the title, and every clause carries information the agent needs.

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

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

With no output schema, the description compensates by enumerating the fields the response carries, and pagination is handled by the schema's page/per_page descriptions. For a zero-required-parameter list tool with annotations covering safety, this is nearly complete; only ordering and pagination defaults are 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 all four parameters (page, per_page, account_id, profile_id) are already documented in the schema, including the 'Agency key only' restriction. The description restates the agency/profile filter semantics with no extra format or boundary detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("List the call-tracking numbers") and then enumerates the returned fields — tracking/destination number, call flow, trigger, recording and messaging flags, last used. That is enough to separate it from the list_* siblings (list_leads, list_profiles, list_web_forms) without opening any schema, and the GET /tracking/numbers endpoint pins the resource precisely.

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?

Explains the key-dependent scoping: a Profile key lists only its own profile, while an Agency key may filter by account_id/profile_id. That tells the agent when the filter parameters are usable, which is the main usage decision here. It does not name an alternative tool (none exists among the siblings) or state exclusions, so it stops short of a 5.

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

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

Annotations already establish readOnly and non-destructive, so the description focuses on what structured fields can't convey: the agency-key auth requirement and the surprising server-side default that start_date becomes today. That default is a genuine behavioral trap an agent would otherwise miss. It doesn't discuss rate limits or response envelope, keeping it at 4.

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 earning its place: scope, auth gate, parameter gotcha, then the endpoint. The most consequential constraint (agency key only) 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 read-only list tool with a fully described 6-param schema, the description covers auth, scope, and the one non-obvious default. With no output schema, the return shape and pagination envelope (next_page) are unstated, but the schema's page description partially compensates.

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, but the description earns an extra point by disclosing the default-to-today behavior of start_date and its filtering semantics (creation date), which the schema omits. The page/per_page pagination params are left entirely to 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 ('list the profiles') and even defines what a profile is ('websites/campaign sets') scoped to one account. An agent can distinguish this from whatconverts_get_profile or whatconverts_list_accounts 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?

'Agency key only' is an explicit precondition that determines whether the agent can call this at all, which is high-value guidance. It stops short of naming an alternative (e.g. 'use get_profile for a single profile'), so it is not full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the agency-key authentication requirement, which is useful, but says nothing about result volume or pagination behavior beyond what the schema already encodes.

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?

Extremely compact and front-loaded, with the constraint stated before the operation. The trailing 'GET /roles' adds little for an agent that already has the tool name, keeping it just short of perfect.

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

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

For a read-only list endpoint with full schema coverage and no output schema, the description supplies the essential auth constraint and endpoint. It is adequate, though naming the returned fields without an output schema leaves the return shape only partially described.

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, order, per_page, role_type) are fully documented in the schema, including enums and defaults. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('list user roles') and names the fields returned, plus the 'agency key only' scoping constraint. It does not explicitly distinguish itself from the sibling whatconverts_get_role, which fetches a single role, 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?

The 'Agency key only' qualifier is a genuine prerequisite that tells the agent when this tool is usable, but there are no explicit when/when-not statements and the single-role sibling (get_role) is never mentioned as the alternative for retrieving one role.

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 read-only, non-destructive and open-world, so the bar is lower; the description still adds two things annotations cannot: agency-key-only authorization and the non-obvious server-side default that start_date silently becomes today. It doesn't mention pagination behavior, though the schema carries next_page.

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

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

Three short clauses plus an endpoint reference; the authorization constraint is front-loaded and the critical start_date gotcha follows immediately. 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 no output schema, the description usefully names the returned fields and covers scope, auth, and date filtering. Minor gap: nothing about paging through results beyond the schema's own page/per_page descriptions.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine semantic meaning by saying start_date/end_date filter on creation date and flagging the today-default trap, which is the main way a caller would silently get an empty result.

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 WhatConverts users') and scopes it ('of the master account or of client accounts'), plus the returned fields (email, role, activation pending). It never names the sibling single-user tool whatconverts_get_user, so differentiation is implied rather than explicit.

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

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

Gives a real prerequisite ('Agency key only') and a concrete usage instruction: pass an early start_date because WhatConverts defaults it to today. It stops short of naming alternatives (e.g. whatconverts_get_user for a single user) or stating 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond them: the auth-key semantics that change what data is visible, plus the underlying endpoint. It does not discuss pagination behavior, which the schema partly handles.

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 with no filler, front-loaded on what is listed before the key-scoping rule. The trailing 'GET /tracking/forms' is marginally redundant but serves as an API reference anchor.

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 naming the fields returned (id, name, match behavior). Pagination is left to the schema, which handles it well, so an agent has what it needs to call this correctly.

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

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

Schema description coverage is 100%, including the 'Agency key only' notes on account_id/profile_id, so the baseline is 3. The description restates that Agency-only filtering constraint but adds no format or interplay detail 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 ('List the web forms WhatConverts tracks') and even enumerates the returned fields (id, name, how the form and its submit are matched). No sibling tool covers web forms, so the scope is unambiguous against the leads/accounts/profiles listers.

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?

Explains the key-dependent usage model clearly: a Profile key returns its own profile's forms, while an Agency key may narrow by account_id/profile_id. It gives the condition for using the filter params, though it names no alternative tool or when-not-to-use 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?

Annotations already declare write/destructive/idempotent/open-world, but the description adds traits the annotations cannot convey: partial-update semantics ('Only the fields you pass change'), that it 'overwrites the previous values of those fields' (what gets destroyed), that it 'Sends no notifications', and the underlying endpoint POST /leads/{lead_id}. This is meaningful side-effect disclosure rather than restatement.

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 'WRITE:' marker, then field scope, then constraints and endpoint in a tight sequence. Slightly dense with the colon-delimited field list, but every clause carries operational information and none 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 7-parameter write tool with nested objects and no output schema, the description covers mutation semantics, required-input constraint, notification behavior and endpoint. Minor omissions remain: no mention of what the response contains or failure/permission behavior, though annotations carry the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3; however the description adds a real constraint not present in the schema — the schema marks only lead_id as required, while the description states 'At least one field is required' among the updatable set. The field enumeration also confirms intent of custom_fields vs additional_fields.

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

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

States a specific verb and resource ('WRITE: update a lead's sales data in WhatConverts') and enumerates the exact updatable fields (quotable, quote_value, sales_value, lead_url, custom/additional fields). This cleanly separates it from whatconverts_create_lead, whatconverts_get_lead and whatconverts_list_leads without needing to open 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?

Gives clear operative conditions: 'At least one field is required' and 'Only the fields you pass change', which tells the agent how to call it. It does not explicitly name alternatives or state when-not to use it (e.g. vs create_lead or a bulk update), so it stops short of full routing guidance.

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