Loops MCP by usefulapi

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

Annotations carry only destructiveHint=true, so the description legitimately adds 'additive' as behavioral context (it adds data rather than replacing an existing record). However, it omits key behaviors an agent needs: what happens when the email already exists (error vs update), permission/auth requirements, and rate limits. Note the mild tension between 'additive' and destructiveHint=true, though these are reconcilable (creation is a state-changing write).

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. The raw endpoint string ('POST /v1/contacts/create') is low-value reference detail for an agent but consumes minimal space, so it does not seriously hurt.

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 9-parameter write tool with nested objects and no output schema, the description is thin: it never says what is returned (e.g., a contact id) or how duplicate emails are handled, both of which matter for calling and chaining the tool 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% across all 9 parameters, including the nested 'properties' and 'mailingLists' objects, so the schema does the heavy lifting. Baseline 3 applies; the description adds nothing about parameter formats or interactions.

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

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

Specific verb+resource: 'Creates a contact in Loops'. The '(additive)' qualifier signals this adds rather than replaces, which nudges it apart from loops_update_contact, but no sibling is named. Clear enough to select 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?

Usage is only implied: '(additive)' hints that this is for contacts that don't yet exist, as opposed to loops_update_contact. There is no explicit when-to-use, when-not, or named alternative despite nine sibling tools in the same domain.

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

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

Annotations declare destructiveHint=true, so the safety burden is partly lifted, and the description usefully frames the operation as an additive schema change and gives the endpoint. However it never states whether the write is irreversible, whether the property name must be unique, or how existing contacts are affected — the exact context the destructive hint begs for. Note the mild tension between 'additive' and destructiveHint=true, which may reflect irreversibility rather than data loss.

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 resource, with no padding. The endpoint restatement is compact and cheap.

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

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

No output schema exists, so return values need not be explained, and both params are fully covered by the schema. Still missing is the behavioral context an agent needs for a schema-mutating write — uniquenes constraints, reversibility, and when creation is appropriate.

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

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

Schema description coverage is 100% and both parameters (name, type) are documented in the schema with an enum for type, so the baseline is 3. The description adds no format, uniqueness, or naming-convention detail 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?

States a specific verb and resource ('Creates a custom contact property/field') and adds scope qualifier ('additive schema change'), which cleanly separates it from loops_list_contact_properties and loops_delete_contact. An agent can tell what this does 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 guidance, no alternative named, and no precondition stated (e.g. check list_contact_properties for an existing definition first). The '(additive schema change)' parenthetical implies a mutation context but does not route the agent to a sibling.

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's 'Destructive.' merely repeats that. It adds no information about permanence, whether the delete is idempotent, what happens when the contact is not found, or auth requirements — the API path is the only extra detail, and it is structural rather than behavioral.

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: action, safety flag, parameter rule, then endpoint. Front-loaded with the operation and zero filler; every sentence 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 two-param destructive tool with no output schema, the essentials (what it does, that it is destructive, how to identify the target) are present. Missing is any behavior on failure or partial-success, which matters for an irreversible operation with optional parameters.

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 adds a genuine constraint not present in the schema: the parameters are mutually exclusive identifiers ('email OR userId'). The schema has zero required fields and no oneOf, so this either/or semantics is real added value.

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 ('Deletes a contact from Loops') and is trivially distinguishable from siblings like loops_find_contact, loops_update_contact, and loops_create_contact. The added endpoint reference (POST /v1/contacts/delete) reinforces the exact operation.

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 gives the identifying condition for calling it ('Supply email OR userId'), which is actionable, but never says when to prefer this over alternatives such as loops_find_contact (to verify before deleting) or how to handle a contact that may not exist. Usage is implied rather than framed.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds the GET endpoint and the runtime rule that at least one identifier must be supplied (a constraint the schema itself does not enforce, since neither param is required), which is genuinely useful. It doesn't disclose what happens when no match is found or the response 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 verb, resource, and identifier rule; the endpoint reference is a compact trailing detail. Nothing is wasted.

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

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

For a simple two-param lookup the core is covered, but with no output schema the description should ideally state what a successful (and unsuccessful) lookup returns to make the tool fully self-contained. As written it leaves the return behavior implicit.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description reinforces the email/userId choice and the at-least-one rule but adds no format or syntax 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 ('Find') and resource ('a contact') plus the two lookup keys, which clearly separates it from the mutating siblings (create/update/delete) and list tools. It stops short of explicitly naming a sibling or specifying that it returns a single contact rather than a collection.

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

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

'Supply at least one' of email or userId gives a usage constraint on the arguments, but there is no guidance on when to prefer this over loops_list_contact_properties or other lookups, nor prerequisites like API-key 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?

The readOnlyHint=true annotation already tells the agent this is a safe, non-mutating read, so the description's main job is to add beyond that — and it adds essentially nothing (no pagination behavior, no auth requirements, no expected size of the result set). The endpoint string confirms the read but is not new behavioral information.

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 purpose, with zero filler. Nothing could be trimmed without losing information.

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

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

For a zero-required-parameter, read-only list tool with a fully documented schema and no output schema, the description covers the essentials. It nonetheless omits what a returned property record looks like (name/type/id), which would help an agent chain into loops_create_contact_property.

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

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

Schema description coverage is 100% and the single enum parameter (all vs custom) is fully documented with its default in the schema. The description adds no syntax or semantics 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 ("List contact fields / custom properties defined in Loops") and even the underlying endpoint, so an agent can tell it apart from write siblings like loops_create_contact_property. It does not, however, explicitly contrast itself with loops_list_mailing_lists or loops_find_contact, so differentiation is only implicit.

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 exclusions, and no mention of alternatives such as loops_create_contact_property for the write path. The only context is the raw REST endpoint, which describes the mechanism rather than the decision.

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

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

readOnlyHint=true already conveys the safe-read profile, so the description's added value is the endpoint (GET /v1/lists) and the return shape (id + name). 'All' implies no filtering and no pagination, which is useful behavior context, but the description says nothing about rate limits, ordering, or empty-account 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 with zero filler; the purpose and the returned fields are front-loaded, followed by the API reference. Every clause 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 zero-parameter read with no output schema, the description supplies what an agent most needs: the resource scope and the shape of the returned records (id + name). It omits pagination/ordering expectations, which is minor given the word 'all', but slightly incomplete.

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

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

The tool takes zero parameters, and schema description coverage is 100%, so the baseline is 4. The description adds that results contain id and name, which is return-value context rather than parameter meaning, but nothing is missing on the parameter side.

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 all mailing lists in the Loops account') and even names the returned fields (id + name), so the purpose is unambiguous. No sibling tool operates on mailing lists (the nearest, loops_list_contact_properties, targets a different resource), but the description does not explicitly draw that line, keeping it short of a 5.

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

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

Usage is only implied: an agent infers this is the enumeration step for listing/audience workflows, but there is no explicit when-to-use, when-not, or prerequisite (e.g. auth setup via loops_test_api_key). With no competing mailing-list tool, there is little to disambiguate, but the description still offers no guidance sentences.

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 carry destructiveHint=true; the description usefully discloses the non-obvious side effect that sending an event TRIGGERS subscribed automations/loops, which is exactly the risk signal an agent needs. It omits other behavioral facts (whether a missing contact aborts the call, idempotency, rate limits), so it is good but not complete.

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 tight sentence with the side effect front-loaded and the raw endpoint appended for reference; no filler and nothing an agent must read past to get the core meaning.

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 nested-object tool with no output schema, the description plus 100%-covered schema plus the destructive hint cover most of what an agent needs. Remaining gaps are behavioral edge cases (mutation semantics on contact creation, failure modes) rather than missing invocation information.

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 email/userId alternation, mailingLists, and property maps are already fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the baseline 3 when structured fields do the work.

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

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

States a specific verb and resource ("Sends an event to Loops for a contact") plus the concrete effect on downstream automations, which lets an agent distinguish it from the contact-CRUD and transactional-email siblings. It stops short of explicitly naming the nearest alternative (loops_send_transactional), leaving that differentiation 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?

The description explains what the tool does but never says when to reach for it versus loops_send_transactional or the contact tools, and lists no prerequisites or exclusions. As with the calibration "update_drive" example, stating behavior is not the same as routing 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 only supply destructiveHint=true, so the description carries the rest of the burden, and it does add real value by stressing that a live email is dispatched to the recipient — the irreversibility that the hint implies but does not spell out. It stops short of disclosing failure modes (invalid transactionalId, rate limits, whether a failed send is retried), so it is strong but not complete.

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 consequential fact (this sends a real email) front-loaded in the first sentence. The trailing 'Loops API: POST /v1/transactional' is transport trivia an agent cannot act on, so it is the one element that does not fully earn its place.

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

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

With no output schema and a nested-object parameter (attachments, dataVariables), the description should ideally say what comes back (message id, success/failure) and how partial failures behave. It covers the core action and its side effect adequately but leaves the caller without return-value or error semantics.

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?

Every one of the five parameters already has a schema description, so the schema does the heavy lifting and a 3 is the baseline. The description adds no syntax, format, or constraint detail beyond what the schema states (e.g. attachment data encoding, how dataVariables map to template placeholders).

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 ('SENDS a real transactional email via a Loops template') and even gives the underlying endpoint, so an agent knows exactly what happens. It implicitly separates itself from the adjacent send_event tool, but never names a sibling explicitly, which is the one thing keeping this from 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 repeated emphasis on 'SENDS' / 'dispatches an actual email' implies the appropriate caution and gives implicit usage context, but there is no explicit when-to-use vs. when-to-use-something-else guidance (e.g. send_event for event-triggered mail, or batch alternatives). Prerequisites such as a valid API key or a pre-existing template id are not stated.

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

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

readOnlyHint=true already establishes the safety profile, and the description adds context beyond that: this is a zero-side-effect GET against /v1/api-key and its observable outcome is the team name. It stops short of describing error behavior for an invalid key.

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 outcome, plus a usage hint and the endpoint. Nothing is padded and nothing essential is omitted.

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-parameter read-only tool with no output schema, the description covers what it does, what it returns, and when to call it. Only the failure mode (what happens with an invalid or missing key) is left implicit.

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

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

The tool takes no parameters, so per the baseline the schema carries no semantic burden and the description need not explain inputs. It correctly signals that the key is read from configuration rather than passed in.

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: verify the configured Loops API key and return the team name. No sibling tool does anything similar (they are all contact/list/event operations), so the agent can distinguish it instantly. It even names the underlying endpoint for precision.

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?

"A good first call" gives clear positive guidance on when to reach for this tool — at the start, to validate credentials before running other Loops operations. There is no competing alternative to exclude, but no explicit statement of what to do when verification fails.

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 destructiveHint=true annotation already flags a write risk, but the description adds non-obvious behavior beyond it: this is an upsert that silently creates the contact when it does not exist. It still omits whether omitted fields are preserved or cleared (partial update vs replace) and how mailingLists/subscribed are reconciled.

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

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

Three short sentences with zero filler; the upsert behavior is front-loaded immediately after the core action so the most decision-relevant fact lands first.

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

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

For a 9-parameter mutation with nested objects and only a single annotation, the description is thin: it says nothing about how custom properties or mailingLists are merged, what happens to omitted fields, or what the call returns. The upsert disclosure covers the biggest ambiguity, but the tool's complexity warrants more.

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 9 parameters is already documented, making 3 the baseline. The description adds only the fact that email/userId serve as the identifying keys, which is marginally useful but largely restates 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 ('Updates (or creates) a contact by email/userId') and clarifies the upsert semantics, plus the underlying endpoint. It does not explicitly contrast with the nearby loops_create_contact sibling, leaving the agent to infer why one would use this instead of a dedicated create call.

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

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

The description conveys a conditional usage rule — 'creates the contact if not found' — which is useful for deciding whether a pre-existing lookup is needed. However, it never names alternatives (loops_create_contact, loops_find_contact) or states when not to use this tool, so routing guidance remains implicit.

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