Keap MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description goes beyond that by disclosing that applying a tag segments the contact and can trigger downstream automation, which is a meaningful side effect an agent must anticipate. It does not, however, mention reversibility, permissions, or rate limits.

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

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

A single front-loaded sentence plus the underlying API endpoint. Every clause earns its place: the verb, the resource, the cardinality, the side effects, and the transport detail, with zero filler.

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

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

For a two-parameter mutation tool with full schema coverage and a destructiveHint annotation, the description covers purpose and side effects adequately. It stops short of covering failure modes (nonexistent tag/contact IDs) and whether the effect can be undone, which would round it out given there is no output schema.

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

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

Schema description coverage is 100% with only two clearly-documented parameters, so the schema already carries the semantic load. The description adds no format, ID-source, or batching detail beyond what the schema provides, making the baseline 3 correct.

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

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

The description states a specific verb and resource ('APPLY a tag to one or more contacts') and adds the scope ('one or more contacts'). It further clarifies the effect ('segments them / can trigger automation'), leaving no ambiguity about what the operation does, and no sibling tool competes for this purpose.

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

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

Usage is implied rather than stated: 'segments them / can trigger automation' hints at why an agent would apply a tag, but there is no explicit when-to-use guidance, no prerequisite (e.g., tag must already exist via keap_list_tags), and no when-not-to-use conditions.

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

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

Annotations only declare destructiveHint=true, so the description carries most of the behavioral burden. It usefully discloses the underlying endpoint and the `extra` merge escape hatch, but says nothing about side effects, authentication/permission needs, duplicate-email handling, or what happens to unspecified fields. With annotations present the bar is lower, but the added context is thin.

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

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

Three short sentences with the action front-loaded, followed by the parameter hint and the endpoint note. Nothing is redundant or padded, though the endpoint detail is the least essential element.

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 6-parameter, all-optional mutation tool with nested objects and no output schema, the description covers the accepted field set and the arbitrary-field escape hatch. However, with no output schema it never says what the response contains (e.g. the new contact id), and it omits mutation side effects, leaving a 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 description coverage is 100%, so all six parameters (given_name, family_name, email_addresses, phone_numbers, company_id, extra) are already documented in the schema. The description merely enumerates them and adds no format, slot, or shape detail beyond what the schema provides, 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?

The description states a specific verb and resource ('CREATE a new contact in the Keap CRM') and even names the underlying API call ('POST /contacts'), so the agent knows exactly what the tool does. It does not explicitly contrast itself with the create/update/get siblings, but the verb 'create' is unambiguous against keap_get_contact or keap_update_contact.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites (e.g. required fields Keap enforces, duplicate-handling behavior, whether an existing contact should be updated instead via keap_update_contact). The sentence about which fields to provide is parameter documentation, not usage guidance.

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

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

Annotations already declare destructiveHint=true, and the description adds only the raw endpoint (POST /tasks). It does not say whether the task is auto-assigned to a user, whether reminders/notifications fire, what permissions are needed, or what a caller gets back. For a write operation with a destructive hint, this leaves real behavioral gaps.

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

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

Two short, front-loaded sentences with no filler; the action and scope come first and the endpoint reference is a compact footnote. Nothing redundant, though the endpoint line is marginal value.

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

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

With 5 parameters, a nested passthrough object, no output schema, and only a destructiveHint annotation, the description is thin but the schema carries the field-level detail. It omits side effects, permissions, and any mention of the 'extra' passthrough, which an agent might need for non-standard Keap fields.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only the optionality of contact linkage and the follow-up/to-do framing, but says nothing about the 'extra' verbatim merge object or due-date expectations.

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 ('CREATE a task') and clarifies scope with 'follow-up / to-do, optionally linked to a contact,' which separates it from keap_get_task and keap_list_tasks. It is clear but does not explicitly name those siblings as the 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?

There is no statement of when to use this versus keap_update_contact, keap_apply_tag, or keap_list_tasks, and no prerequisites or exclusions are given. The only implied guidance is the optional contact linkage.

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

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

readOnlyHint=true already declares this as a safe read, so the bar is lower. The description adds only the API endpoint mapping and nothing about 404/not-found behavior or what a failed lookup returns; it neither contradicts nor meaningfully extends the annotation.

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

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

Two short sentences, front-loaded with the action and scoped by id, followed by the exact endpoint for cross-reference. No filler at all.

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

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

For a simple single-resource read with full schema coverage and annotations declaring read-only status, this is nearly complete. The only gap is that with no output schema, nothing hints at the shape or size of the returned company object.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema itself. The description adds no field-selection syntax guidance for the 'fields' parameter or id format, which is acceptable given the schema carries the load.

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

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

States a specific verb and resource ('Get a single company by id') plus the underlying REST endpoint, so the agent knows exactly what is fetched. It never names the sibling it must be distinguished from, notably keap_list_companies, so differentiation is left to inference.

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

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

Usage is implied by 'by id' versus the list variant, but there is no explicit when-to-use statement, no precondition, and no named alternative. An agent can infer the case, but the description does no routing work.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered structurally. The description adds the backing endpoint (GET /contacts/{contact_id}), which is useful context, but says nothing about not-found behavior, auth requirements, or what a miss returns.

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 core action (get one contact) followed by the API mapping. Nothing is redundant or padded.

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

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

A simple single-record read whose annotations carry the safety profile and whose schema fully documents inputs, so it is mostly adequate. However, with no output schema, the description gives no hint about the returned contact shape or how 'fields' affects the response.

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

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

Schema coverage is 100% and both parameters are documented in the schema, including the 'fields' selection parameter. The description adds no syntax, format, or examples beyond that, 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 with scope: 'Get a single contact by id.' The word 'single' implicitly distinguishes it from keap_list_contacts and keap_get_company, but the sibling is not named explicitly, so it stops short of the top score.

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 phrase 'by id' implies the precondition (you need a contact_id) and the single-record use case, but there is no explicit when-to-use guidance, no mention of keap_list_contacts as the alternative for lookups without an id, and no exclusion cases.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. Beyond that the description adds only the underlying REST endpoint, which is not meaningful behavioral context for an agent; it says nothing about behavior when the id is absent, error handling, or returned data.

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

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

Two short sentences with no filler, and the core action is front-loaded. The trailing endpoint reference is slightly redundant but harmless retrieval context.

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

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

For a simple single-record read with annotations covering the read-only nature, the definition is minimally sufficient. With no output schema, it could usefully indicate what the returned opportunity contains or how missing ids are handled, so it is adequate rather than complete.

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

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

Schema description coverage is 100% for the single required opportunity_id, so the schema already carries the parameter documentation. The description adds no format, source, or constraint detail beyond restating 'by id', which is the baseline case.

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

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

States a specific verb ('Get') and resource ('a single opportunity by id'), which cleanly distinguishes it from the sibling list tools such as keap_list_opportunities. It is clear but never names or contrasts with a sibling, 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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. The only usage signal is inferred from the name/verb, which is insufficient for a 5-point score.

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

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

The readOnlyHint=true annotation already establishes this is a safe read, so the description's main added value is mapping the operation to the underlying REST call 'GET /tasks/{task_id}'. It says nothing about error behavior (e.g., missing id), auth requirements, or return shape.

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 operation before the endpoint mapping. Efficient, though the endpoint path is largely redundant with the tool name and could be considered filler.

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

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

For a single-parameter read tool with full schema coverage and a readOnly annotation, the definition covers the essentials. However, with no output schema, an agent gets no indication of what a task object contains or what a failure returns.

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

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

Schema description coverage is 100% for the single task_id parameter, so the schema already documents it. The description only restates 'by id' without adding format, source, or validation detail beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource with scope ('single task by id'), which distinguishes it from keap_list_tasks implicitly. It stops short of explicitly naming the list sibling as the alternative, so it is clear but not maximally differentiated.

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

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

The description says what the tool does but gives no when-to-use context, no prerequisites, and does not name keap_list_tasks or any other sibling as the alternative for broader queries. Usage must be inferred from the name and parameter.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results support filtering, ordering, and cursor pagination, though the schema's page_token description already discloses the cursor mechanics. It says nothing about result shape or rate limits, so it adds only modest value beyond structured data.

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

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

Two front-loaded sentences plus a short endpoint mapping, with no wasted prose. Slightly downgraded because 'Keap: GET /affiliates' adds little for an agent that already has the tool. Efficient overall.

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 four-parameter read-only list endpoint with full schema coverage and no output schema, the description covers purpose and pagination behavior sufficiently. It omits any hint of the affiliate record fields returned, but with no output schema this is a minor gap.

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

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

Schema description coverage is 100%, so all four parameters (filter, order_by, page_size, page_token) are already documented with syntax and examples in the schema. The description adds no parameter-level detail beyond that. Baseline 3 is correct when the schema does the heavy lifting.

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

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

Names a specific verb and resource ('List referral-program affiliates'), and the 'referral-program' qualifier clarifies what an affiliate is. It does not explicitly distinguish itself from sibling list tools (contacts, campaigns, etc.), but the resource name uniquely identifies it. Clear enough to select correctly among siblings.

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 'list' verb; the description never states when to prefer this over other list tools or what preconditions apply. The capability note about filtering/ordering/pagination gestures at context but offers no alternatives or exclusions. Adequate but with a clear gap.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description usefully adds that results are cursor-paginated and filterable, but says nothing about auth scopes, rate limits, or default page size behavior beyond what the schema states.

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

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

Two sentences plus an endpoint note, front-loaded with purpose before capabilities. The 'Keap: GET /campaigns' line is borderline redundant but plausible as documentation mapping, so sizing is close to optimal.

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 full schema coverage and no output schema, the description covers purpose and pagination, which is the main behavioral concern. It could note the shape of the returned list (campaigns plus next_page_token), but nothing critical 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%, so all four parameters (filter, order_by, page_size, page_token) are already documented with examples. The description only restates these capabilities at a high level, adding no syntax or format 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 marketing campaigns') and immediately disambiguates the domain term with '(automation sequences)'. Among siblings like keap_list_contacts, keap_list_tags, and keap_list_tasks, the resource 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?

It states supported capabilities (filtering, ordering, cursor pagination), which implies how to drive the tool, but gives no explicit when-to-use, prerequisites, or alternatives (e.g., a get-by-id sibling). Usage is inferable rather than guided.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds that results are cursor-paginated and that field selection is available, which is useful context beyond the annotation. It does not describe the pagination response shape (next_page_token) or default/empty-filter 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?

Three short sentences, front-loaded with the core action, and the capability summary is compact. The trailing 'Keap: GET /companies' is minor mapping detail rather than filler, so little 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?

With no output schema, the agent gets no description of the returned record shape or the pagination envelope, which matters for a list endpoint that paginates. Five parameters and the read-only annotation are otherwise well covered, so the gap is moderate rather than severe.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the filter syntax example and the page_size maximum and page_token origin. The description only restates the categories of parameters, adding no syntax or format 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 companies in the Keap CRM'), which clearly separates it from the singular keap_get_company and from other list tools such as keap_list_contacts. It does not explicitly name those siblings, so it falls short of the top tier.

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?

Lists the supported capabilities (filtering, ordering, field selection, pagination) but never says when to use this versus keap_get_company for a single record or another list endpoint. Usage is implied by the capability list rather than stated.

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

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

readOnlyHint=true already establishes this as a safe read, so the bar is lower. The description adds useful behavioral context by naming cursor pagination and the page_size/page_token mechanism, but says nothing about rate limits, result caps, or what a response contains (e.g., next_page_token), which matters for a paginated listing call.

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, front-loaded with what the tool does before capability detail. Every clause carries information and nothing is redundant.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers purpose, capabilities, and pagination – enough for an agent to call it correctly. It could be strengthened by hinting at the pagination response cursor, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters with examples (filter expression syntax, order_by negation, max page size). The description only restates the same categories (filtering, ordering, field selection, pagination) without adding syntax or format detail beyond the schema. Baseline 3 is correct 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 states a specific verb and resource ('List contacts in the Keap CRM') and even names the backing endpoint (GET /contacts), so the agent knows exactly what operation is performed. It is clearly separable from siblings like keap_get_contact or keap_create_contact by the verb alone, though it never explicitly differentiates itself from them.

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

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

It lists the capabilities (filtering, ordering, field selection, pagination) which implies browsing/searching use cases, but gives no explicit when-to-use versus when to use keap_get_contact or a filtered list instead. Usage is inferable rather than stated.

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

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

readOnlyHint=true already declares this is a safe non-mutating read, so the annotation carries the safety burden. The description adds that pagination is cursor-based, which is mild behavioral context, but says nothing about default result size, rate limits, or total-count behavior.

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

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

Two tight sentences, front-loaded with the purpose before the capability list and the raw endpoint. Nothing is wasted, though the trailing 'Keap: GET /opportunities' is the least valuable element.

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

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

No output schema exists, so the description arguably could hint at the return shape, but for an optional-parameter list tool whose pagination and filtering are fully documented in the schema, an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so every one of the five parameters is already documented in the schema with examples. The description's mention of filtering, ordering, field selection, and cursor pagination merely restates the schema at a higher level, adding no syntax or constraint 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?

States a specific verb and resource ('List sales opportunities (deals) in the pipeline'), with the '(deals)' gloss clarifying domain vocabulary. The plural 'opportunities' plus the sibling keap_get_opportunity makes the read-many vs read-one distinction inferable, though no sibling is named explicitly.

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

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

The description implies usage by advertising capability (filtering, ordering, field selection, cursor pagination) but never says when to reach for this tool versus keap_get_opportunity or the other list_* siblings, and offers 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, so safety is covered. The description adds useful behavioral context by disclosing that results support filtering, ordering, and cursor pagination. It does not detail rate limits, default ordering, or return shape, so it adds value but stops short of rich disclosure.

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

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

Three tight sentences: resource first, capabilities second, endpoint mapping last. Nothing is wasted and the most important information is front-loaded.

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

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

For a read-only list tool whose parameters are fully documented in the schema and whose safety profile is in the annotations, this is nearly complete. The mention of cursor pagination is the key operational detail an agent needs; return format is not described but no output schema exists to defer to.

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

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

Schema description coverage is 100%, so every parameter (filter, order_by, page_size, page_token) is already documented with examples and constraints. The description restates that filtering/ordering/pagination exist but adds no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('List e-commerce orders'), clearly setting it apart from the contact/company/task list siblings, which cover different resources. It is clear but does not explicitly name or contrast with any alternative 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?

There is no when-to-use guidance, no prerequisites, and no exclusions. The agent must infer that this is the correct tool for orders purely from the resource noun in the purpose sentence.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful capability context (filtering, ordering, cursor pagination) and the underlying GET endpoint, but says nothing about return format, page size defaults, or result limits.

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

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

Three short sentences, front-loaded with purpose, then capabilities, then the API endpoint. Every sentence carries information and none is redundant.

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

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

For a read-only, cursor-paginated list tool with a fully documented schema and no output schema to explain, the definition is adequately complete; the only minor gap is absence of any return-shape or pagination-usage hint.

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 all four parameters carry descriptions with syntax examples, so the schema does the heavy lifting. The description only names the categories of parameters generically and adds no semantics beyond them, which matches the baseline 3.

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

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

States a specific verb and resource ('List products in the catalog'), which clearly separates it from the list_* siblings by resource. It doesn't explicitly name or contrast with a sibling, but the resource is unique enough that 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?

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives. The description only states capabilities (filtering, ordering, pagination), leaving the agent to infer that this is the catalog enumeration tool.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context beyond the annotation by identifying the underlying endpoint and confirming cursor-style pagination, but it discloses nothing about rate limits, auth scopes, or result volume behavior.

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

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

Two short sentences that are front-loaded with the resource and then the capabilities. No filler, no repetition of the title, and the endpoint mapping is compact.

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 zero-required-param read tool with a fully documented schema, a readOnly annotation, and no output schema, the description covers the essentials including the pagination model. It could be stronger by noting how next_page_token is consumed, but nothing critical for invoking it 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%, so the schema already documents filter syntax, order_by, page_size cap, and page_token origin. The description adds only a generic mention of filtering/ordering/pagination, 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 pair ('List recurring subscriptions / payment plans') and pins it to the Keap GET /subscriptions endpoint. It is clearly distinguishable from resource siblings like keap_list_orders or keap_list_contacts, though it does not explicitly name a sibling it must not be confused with.

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 names supported capabilities (filtering, ordering, cursor pagination) but never states when to use this tool versus alternatives or any prerequisites. Usage is only implied by the resource name, which is the minimum viable level.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful behavior beyond the annotation by disclosing filtering, ordering, and cursor pagination support, but omits rate limits, default page size behavior, and what a bare/empty account returns.

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 core purpose, then capability, then the API reference. No filler and nothing redundant; 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 four fully documented optional parameters and a readOnlyHint, the definition supplies enough to invoke the tool correctly. The only shortfall is that with no output schema, it doesn't mention the shape of results or that a next_page_token cursor is returned to drive the advertised pagination.

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 filter, order_by, page_size, and page_token with examples. The description only restates the general capability ('supports filtering, ordering, and cursor pagination') without adding syntax or defaults, so baseline 3 applies.

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

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

States a specific verb and resource ('List tags defined in the account'), adds scope context (used to segment contacts), and cites the underlying endpoint GET /tags. This clearly separates it from the sibling keap_apply_tag, which mutates tag state rather than enumerating it.

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

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

The description implies when the tool is useful (retrieving the tag vocabulary used for segmentation) but never states explicit conditions, exclusions, or alternatives. It does not direct the agent to keap_apply_tag for write operations, leaving the list-vs-apply choice to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful operational context — that ordering and cursor-based pagination are supported and which REST endpoint backs it — but says nothing about rate limits, response shape, or default ordering.

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 core action before the capability list. The endpoint mapping is borderline trivia but cheap and useful for API-aware agents; 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 read-only list tool with full schema coverage the description covers the mechanics (filter/order/paginate). However, there is no output schema, and the description never indicates what a task record contains or how results are ordered by default, leaving the return surface undocumented.

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 (filter, order_by, page_size, page_token) are already documented with examples. The description's mention of 'filtering, ordering, and cursor pagination' only restates the schema at a high level, so baseline 3 applies.

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

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

States a specific verb and resource ('List tasks') and disambiguates the resource with synonyms ('follow-ups / to-dos'), plus maps to the underlying endpoint ('Keap: GET /tasks'). It doesn't explicitly name siblings (e.g., keap_get_task for a single task) but the singular/plural distinction is self-evident.

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

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

No when-to-use or when-not guidance, and no pointer to alternatives like keap_get_task or keap_create_task. The agent can only infer usage from the tool name; nothing indicates when filtering or pagination is appropriate versus other list tools.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the behavioral load and does so well: it discloses merge semantics ('only supplied fields are changed') and that `extra` is merged verbatim, which are the traits an agent most needs to avoid clobbering data. It does not state permission requirements or what the call returns, so it falls short of a 5.

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

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

Three compact sentences, front-loaded with the core action and the id requirement, then the mutation semantics, then the raw endpoint for API-level mapping. No filler or repetition.

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

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

For a mutation tool with full schema coverage and no output schema, the description covers the action, the required id, the field set, and partial-update behavior. The one meaningful omission is what happens on return (updated contact object vs. empty body), which an agent editing a contact might need to confirm.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema and the baseline is 3. The description enumerates the same field names (given_name, family_name, email_addresses, phone_numbers, company_id, extra) without adding syntax, format, or slot conventions beyond what the schema already provides.

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

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

The description gives a specific verb and resource ('UPDATE an existing contact by id') and the word 'existing' plus the id requirement cleanly separates it from keap_create_contact, keap_get_contact, and keap_list_contacts. The added Keap endpoint mapping (PATCH /contacts/{contact_id}) reinforces exactly which operation this is.

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

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

Usage is implied rather than stated: the agent can infer this is for modifying a contact that already exists, and the 'only supplied fields are changed' clause signals a partial-update pattern. However, there is no explicit when-to-use rule, no prerequisite/permission guidance, and no direct pointer to siblings like create_contact or get_contact.

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