Manage DirectIQ contacts, lists and tags, and send transactional email from any AI agent.
Scored across 15 tools
Most tools target a distinct resource+action (get_contact vs get_list vs get_tag, list vs create variants). The overlap is the generic directiq_read_request/directiq_write_request escape hatches, which can do everything a dedicated tool can, plus slight redundancy between account_overview and contact_count. Descriptions do steer agents toward dedicated tools first, so confusion is limited.
Every tool follows the same snake_case verb_noun pattern with a uniform directiq_ prefix (list_contacts, create_tag, get_list, update_contact). The two generic tools (read_request, write_request) still fit the verb_noun convention.
15 tools is a well-scoped set for a contacts/lists/tags/send API, split cleanly into dedicated CRUD-lite tools plus endpoint discovery and two generic request tools. Each tool covers a distinct operation rather than padding the surface.
Read and create coverage is solid for contacts, lists, and tags, but there are notable gaps: no create_contact, no delete for contacts/lists/tags, and no list/tag update. The generic write_request (with list_endpoints for discovery) provides a workaround, keeping this a minor rather than blocking gap.
Summarize the account: total contacts, active/disabled status counts, list count, tag count, and confirmed sender addresses. Individual sections degrade gracefully if unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real value beyond them: 'Individual sections degrade gracefully if unavailable' tells the agent to expect partial results rather than an outright failure, which is exactly the kind of behavioral trait annotations cannot express. It stops short of saying anything about cost, latency, or ordering of the sub-fetches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero waste. The inventory of sections is front-loaded and the degradation caveat is placed as a qualifier at the end where it belongs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully compensates by enumerating the return sections, and the graceful-degradation note sets expectations for partial payloads. Missing only minor details such as whether the response is a flat object or how unavailable sections are represented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4; there is nothing for the description to clarify. The description adds no per-parameter information, but none is needed.
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 ('Summarize') plus resource ('the account') and an explicit enumeration of the returned sections (contact totals, status counts, lists, tags, sender addresses). This reads clearly as an aggregate/dashboard tool and is implicitly distinct from the granular siblings, but it never names them (e.g. directiq_contact_count, directiq_list_lists) to make the distinction 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?
The aggregation framing implies 'use this for a quick account snapshot', but there is no explicit when-to-use statement and no guidance on when to prefer the individual sibling tools (directiq_contact_count, directiq_list_lists, directiq_list_tags) over this one. The alternative choice is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the total number of contacts in the account.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and side-effect profile is fully covered structurally. The description adds only the account-wide scope ('in the account'), and does not say what the count reflects (e.g. included/excluded statuses) or the return type, which is a minor gap given the annotation coverage.
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 with zero filler. Nothing could be removed without losing 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 zero-parameter, no-output-schema tool with complete annotations, this is nearly sufficient. A brief note on what the returned count represents (or that it returns an integer) would close the only remaining gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The phrase 'in the account' correctly signals there is no filtering input.
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 ('total number of contacts in the account'), making the aggregate-count purpose clear. It does not, however, distinguish itself from siblings like directiq_list_contacts or directiq_account_overview, which an agent could plausibly confuse it 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?
Usage is only implied: an agent can infer this is the lightweight counting alternative to directiq_list_contacts, but the description never says so or states when not to use it. No prerequisites or alternative routing are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new contact list.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | List name (max 200 characters) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description merely restates that this creates a list and adds no behavioral context such as duplicate-name handling, permissions, or side effects. With annotations covering the safety profile, the description adds little beyond the minimum.
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 a single, front-loaded sentence with no wasted words. It is efficient, though its extreme brevity leaves no room for useful 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 one-parameter create tool, the schema fully documents the required name field and annotations cover the safety profile. The description still omits any mention of duplicate-list behavior, return value, or operational caveats, leaving clear gaps for an agent invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the sole parameter 'name' is fully documented with min/max length. The description adds no meaning beyond the schema, so the baseline of 3 is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb plus resource: 'Create a new contact list.' This clearly identifies the operation and distinguishes it from read siblings like directiq_list_lists or directiq_get_list. However, it does not explicitly differentiate from directiq_create_tag, the other create sibling.
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 such as directiq_create_tag or directiq_list_lists. The description provides no context, prerequisites, or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tag.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Tag name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not mention what happens if the tag name already exists, whether names must be unique, or what is returned.
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 one-sentence description is front-loaded and contains no padding. However, its brevity reflects under-specification rather than true economy, leaving little for an agent to work with.
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?
This is a mutation tool with no output schema, and the description does not explain the result of a successful create, the duplicate-name behavior, or what the new tag looks like. Compared with the coverage the annotations provide, the description is 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?
Schema coverage is 100% for the single 'name' parameter, so the baseline is 3. The description adds no meaning beyond the schema, such as naming constraints or uniqueness rules, so it earns no more than that.
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 concrete verb and resource ('Create a new tag'), which clearly separates it from siblings such as directiq_get_tag, directiq_list_tags, and directiq_create_list. It is unambiguous but does not explicitly contrast itself with those 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?
There is no guidance on when to use this tool versus alternatives like directiq_get_tag or directiq_list_tags, and no prerequisites or exclusions are stated. The usage is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single contact by its numeric ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Numeric contact ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on what happens when the ID doesn't exist (error vs. empty), no auth or scope details, and no pagination/return context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short, front-loaded sentence with no filler. It is efficient, though its brevity is partly because little information is conveyed 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 trivial single-parameter lookup with full schema coverage and rich annotations, the description is minimally adequate. Still, it leaves the not-found behavior and relationship to the list/update siblings unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is fully documented, so baseline is 3. The description's phrase 'numeric ID' merely echoes the schema's 'Numeric contact ID' without adding format or range insight beyond the exclusiveMinimum constraint already present.
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 contact'), plus the lookup key. This clearly distinguishes it from the sibling bulk lister directiq_list_contacts, though it doesn't explicitly name that sibling.
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 guidance, no prerequisites, and no mention of alternatives despite several contact-related siblings (directiq_list_contacts, directiq_update_contact). The singular/plural distinction is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a contact list by its numeric ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Numeric list ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that retrieval is by numeric ID and does not add further behavioral context beyond the annotations.
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 a single front-loaded sentence with no wasted words. It states the action, resource, and key input constraint 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?
For a simple single-parameter lookup tool with rich annotations and full schema coverage, the description is nearly sufficient. It lacks any return-value context, but no output schema exists and the core invocation need is covered.
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 parameter, and the schema documents 'Numeric list ID' with type integer and exclusiveMinimum 0. The description’s mention of numeric ID matches but does not add meaning 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?
The description states a specific verb and resource: 'Get a contact list by its numeric ID.' This clearly distinguishes fetching a single list from list_lists or create_list, though it does not explicitly name the sibling 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?
Usage is implied: call this when you already have a numeric list ID. However, the description gives no explicit when-to-use guidance, prerequisites, or comparison to alternatives such as directiq_list_lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a tag by its numeric ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Numeric tag ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that — no behavior on unknown IDs, no error semantics, no indication of what a tag record contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the verb and lookup key front-loaded and zero filler. It is efficient, though its brevity is the same thing that leaves usage and return context unaddressed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with full annotation coverage and no output schema, this is minimally sufficient. It leaves out what the returned tag looks like and what happens for a nonexistent ID, which an agent might need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the id parameter is documented as 'Numeric tag ID' with exclusiveMinimum 0. The description's phrase 'numeric ID' merely restates the schema, 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 ('Get a tag') and narrows the lookup to a numeric ID, which implicitly separates it from directiq_list_tags and directiq_create_tag. It does not explicitly name those siblings, so it stops short of full differentiation.
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 no guidance on when to use this versus directiq_list_tags (e.g., 'use when you already know the tag ID'). There are no stated preconditions or exclusions; the agent must infer usage from the parameter alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contacts, optionally paginated.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number | |
| pageSize | No | Results per page (max 500) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds only that pagination is optional, with no mention of ordering, default page size, total counts, or what happens at the end of the list — thin 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?
A single short sentence with no waste and the resource front-loaded. It is efficient but borders on under-specified rather than genuinely tight.
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 should say something about the returned shape — whether it includes pagination metadata or a contact list — and it says nothing. For a list tool whose sibling directiq_contact_count exists, the missing relation and return description leave real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with 'page' documented as 1-based and 'pageSize' capped at 500, so baseline 3 applies. The description's 'optionally paginated' merely restates that both parameters are optional and adds no format or default guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('List contacts') that an agent can match against siblings like directiq_list_lists or directiq_list_tags. It doesn't explicitly differentiate from directiq_contact_count or directiq_get_contact, but the resource naming makes the distinction inferable.
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 statement of when to prefer this over directiq_contact_count or directiq_get_contact, and no prerequisites. The only usage hint is 'optionally paginated', which is about mechanics rather than tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List known DirectIQ API operations (HTTP method, API group, path, summary). Optionally filter by a search term. Call GET operations with directiq_read_request and POST/PUT/PATCH/DELETE operations with directiq_write_request.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Optional case-insensitive filter matched against each operation path or summary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description does not need to restate safety. It adds useful behavioral context by describing what is returned (method, group, path, summary) and that filtering is case-insensitive, though it does not mention pagination 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 with zero waste. The core purpose and return fields are front-loaded, and the routing guidance follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by naming the returned fields. Combined with the clear routing to the read/write execution siblings, an agent has everything needed to call this discovery 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%, so the schema already documents the single 'search' parameter including case-insensitivity and match targets. The description only says 'search term', adding no syntax, format, or matching 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?
States a specific verb and resource ('List known DirectIQ API operations') and enumerates the returned fields (HTTP method, API group, path, summary). It also distinguishes itself from the sibling execution tools by naming directiq_read_request and directiq_write_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call GET operations with directiq_read_request and POST/PUT/PATCH/DELETE operations with directiq_write_request, which is exactly the routing decision an agent needs. The optional 'search' filter is described as an alternative narrowing path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all contact lists.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the word 'all,' implying no filtering, but says nothing about result size, pagination, or ordering that an agent would need for a 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?
A single front-loaded sentence with no filler, appropriate for a trivial no-argument tool. It earns its place but stops short of adding the one clause (pagination or result scope) that would make it fully useful.
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, no parameters, and rich annotations, the description only needs to cover return expectations and pagination — which it does not. Adequate for identification, incomplete for invocation confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters in the schema, so the baseline applies; there is nothing for the description to disambiguate. The description correctly implies a no-argument call.
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 contact lists'), which cleanly separates it from siblings like directiq_list_contacts and directiq_list_tags by resource. However, it never explicitly contrasts itself with directiq_get_list, so sibling differentiation is only implicit through the resource noun.
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 guidance on when to call this versus directiq_get_list (single list), nor any mention of prerequisites, account scoping, or pagination behavior. The agent must infer everything about selection from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already carry the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the burden is low, but the description adds essentially nothing beyond the tool name — no note on result set size, pagination, ordering, or whether a full dump is safe to call repeatedly. The one small signal is "all", implying no server-side filtering.
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 short sentence, front-loaded with the action and resource, with zero filler. For a zero-parameter tool this is an appropriate size, though it borders on under-specification rather than deliberate brevity.
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 input parameters and no output schema, the description is the only place an agent could learn what a "tag" looks like or whether the response is paginated, and it says neither. The annotations cover behavior, so the omission is not fatal, but the definition is thinner than the tool's result set warrants.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics left to explain. Nothing in the description contradicts the empty 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 all tags"), which is unambiguous and clearly distinct from singular siblings like directiq_get_tag and mutating siblings like directiq_create_tag. It stops short of naming an alternative explicitly, which keeps it below 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 by the name and the word "all" — an agent can infer this is the bulk-retrieval path versus directiq_get_tag, but the description never says when to prefer one over the other or whether any prerequisite exists. No exclusions or alternatives are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue an authenticated GET request to any DirectIQ endpoint. Use directiq_list_endpoints to discover GET operations (group, path) that have no dedicated tool. Full request/response schemas for each group are in the DirectIQ API docs at https://rest.directiq.com/{group}/swagger/index.html (core, contacts, subscription).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Endpoint path within the group, e.g. '/contact/list' or '/email/send' | |
| group | Yes | DirectIQ API group: core, contacts, or subscription | |
| query | No | Optional query parameters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds value by disclosing that requests are authenticated and by pointing to the per-group swagger docs for full request/response schemas, which the annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: capability first, discovery mechanism second, schema reference third. The long docs URL is functional content, not padding.
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 generic pass-through tool with no output schema, the description covers what it does, how to find valid inputs, and where return shapes are documented. It stops short of stating error behavior or whether the response is passed through verbatim, which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns an extra point by telling the agent that the authoritative definition of valid paths and query parameters lives in the group-specific swagger page. That directly helps populate the free-form 'query' object, which the schema only types generically.
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 ('Issue an authenticated GET request to any DirectIQ endpoint') and the word GET immediately distinguishes it from the sibling directiq_write_request. The escape-hatch nature for endpoints without a dedicated tool is 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?
Names the precondition for use ('GET operations that have no dedicated tool') and routes the agent to directiq_list_endpoints to discover valid (group, path) pairs. This implicitly and clearly excludes endpoints already covered by the many dedicated siblings like directiq_get_contact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a transactional email.
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | CC recipients | |
| to | Yes | Recipient email address | |
| bcc | No | BCC recipients | |
| from | Yes | Sender email address (must be a confirmed sender) | |
| content | Yes | Email body (HTML or text, min 2 characters) | |
| subject | Yes | Email subject (min 2 characters) | |
| fromName | No | Sender display name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish that this is a non-read-only, open-world, non-idempotent operation, so the safety profile is covered. The description adds only the word 'transactional' and does not explain delivery behavior, rate limits, sender-confirmation requirements, or what happens on failure.
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 single sentence is concise and front-loaded with the core action. It does not waste words, though it is terse enough that a little more structure could improve routing.
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 seven-parameter, open-world mutation with no output schema, the description is too thin. The schema covers parameters and annotations cover safety, but the agent gets no behavioral context about delivery, responses, or operational constraints.
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 all seven parameters documented, including required fields and sender confirmation. The description adds no parameter meaning 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 clear verb and resource ('Send a transactional email'), so the agent knows the core action. It does not distinguish this tool from siblings like directiq_write_request or directiq_read_request, which leaves ambiguity about when this specialized sender applies.
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 generic write/request siblings, nor any prerequisites or exclusions. The agent must infer usage from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a contact by ID. Provide the fields to change (e.g. firstName, lastName, email).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Numeric contact ID | |
| fields | Yes | Object of contact fields to update |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The phrase 'fields to change' usefully implies a partial update where unlisted fields are preserved, but the description never states that explicitly nor mentions any permission or irreversibility caveats.
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, action stated first, no filler. Every clause carries information about invocation.
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?
The nested `fields` object has no key enumeration in the schema, and the description only offers three illustrative names, leaving the valid field vocabulary largely unknown. Acceptable for a simple two-param tool with full annotation coverage, but not complete given the open-ended nested payload.
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, and the description earns an extra point by naming example field keys (firstName, lastName, email) for the free-form `fields` object, which the schema leaves as an unconstrained additionalProperties map.
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 ('Update a contact by ID'), which is enough to separate it from read siblings like directiq_get_contact and directiq_list_contacts. It does not explicitly name a sibling alternative, 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?
'Provide the fields to change' tells the agent what to supply but not when to choose this tool over alternatives such as directiq_write_request or directiq_create_list. There are no preconditions, no when-not guidance, and no pointer to a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue an authenticated POST, PUT, PATCH, or DELETE request to any DirectIQ endpoint. May create, modify, or permanently delete account data. Use directiq_list_endpoints to discover operations (method, group, path) that have no dedicated tool. Full request/response schemas for each group are in the DirectIQ API docs at https://rest.directiq.com/{group}/swagger/index.html (core, contacts, subscription).
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Optional JSON request body: an object, or an array for bulk operations | |
| path | Yes | Endpoint path within the group, e.g. '/contact/list' or '/email/send' | |
| group | Yes | DirectIQ API group: core, contacts, or subscription | |
| query | No | Optional query parameters | |
| method | Yes | HTTP method |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces this with 'may create, modify, or permanently delete account data', so the risk profile is unambiguous. It does not cover failure modes, rate limits, or whether any confirmation step exists, which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler: capability plus risk profile first, then discovery alternative, then where to find schemas. Nothing is repeated from the schema and the most decision-relevant 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 an open-ended generic HTTP passthrough with untyped body/query, the critical missing piece is where request shapes come from, and the description supplies per-group swagger URLs. Return shape is only partially addressed and there is no output schema, but that is a minor gap for this tool class.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema documents group enum, method enum, path pattern, query, and body shapes, so the baseline of 3 applies. The description adds one piece of real value by mapping the group value to a concrete swagger URL, but adds no syntax guidance for path or query beyond the schema examples.
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 set (issue POST/PUT/PATCH/DELETE) and resource (any DirectIQ endpoint), and explicitly positions the tool as the escape hatch for operations with no dedicated tool. An agent can distinguish it from directiq_read_request and the dedicated create/update tools 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?
Names the alternative (directiq_list_endpoints) for discovering method/group/path, and scopes use to operations that lack a dedicated tool, which implies the reverse exclusion (prefer dedicated tools). It also routes the agent to the per-group swagger docs for schemas it cannot infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
directiq_account_overviewdirectiq_contact_countdirectiq_create_listdirectiq_create_tagdirectiq_get_contactdirectiq_get_listdirectiq_get_tagdirectiq_list_contactsdirectiq_list_endpointsdirectiq_list_listsdirectiq_list_tagsdirectiq_read_requestdirectiq_send_emaildirectiq_update_contactdirectiq_write_requestEmail for AI agents: send mail, manage contacts, automations & webhooks. Zero-DNS first send.
Email, WhatsApp and Telegram for AI agents: send, campaigns, automations, contacts, agent inboxes.
AI-native email marketing. Campaigns, automations, transactional, contacts, and analytics.
Send transactional emails for AI agents via SMTP. Templates included.
Add one secure layer between your agents and this server.
