Drupal MCP by usefulapi

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

Annotations already declare destructiveHint=true, so the write nature is covered. The description adds the wire-level behavior (POST endpoint, 201 response, request body shape), which is genuinely useful, but omits practical behavioral facts: authentication/CSRF requirements, permission implications, and side effects such as field validation or auto-generated UUIDs/aliases. No contradiction with destructiveHint=true.

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

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

Extremely compact and front-loaded: the core action leads, followed by endpoint and body contract. Every clause carries information and nothing is padded or repeated from the schema.

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, and the description compensates by stating the success status (201). Combined with the full 100%-covered input schema including nested-object examples for attributes and relationships, an agent has enough to invoke 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%, so the baseline is 3, but the description goes further by mapping the parameters onto the JSON:API payload structure: 'type: entity_type--bundle, attributes, relationships?'. This clarifies how entity_type/bundle are recombined and where attributes/relationships sit, which is real added 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?

States a specific verb+resource ('Create a new resource (content entity)') and scopes it to an entity_type/bundle, plus gives the exact JSON:API endpoint ('POST /jsonapi/{entity_type}/{bundle} → 201'). The create semantics implicitly separate it from get/list/update/delete siblings, but no sibling is named for explicit 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?

Usage is only implied by the verb 'create' and the POST endpoint mapping. There is no guidance on when to prefer this over drupal_update_resource, no prerequisite/auth context, and no exclusions. An agent can infer the intent but must guess at preconditions.

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 set destructiveHint=true, and the description adds genuinely useful behavioral detail: the exact HTTP verb/path and the '204 (empty body)' outcome with a small confirmation. It stops short of noting irreversibility, cascading effects (e.g., deleting a taxonomy_term with children), or failure modes.

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 clauses: purpose, endpoint contract, and return expectation. Nothing is wasted and the key action is front-loaded in the first sentence.

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, and the description compensates by stating the response shape ('204 empty body, small confirmation'). For a destructive mutation the coverage is good; a note on permanence or permission requirements would make it complete.

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

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

Schema coverage is 100%, so the three parameters are fully documented in the schema. The description reinforces that the UUID (not numeric id) is what JSON:API uses and shows the {entity_type}/{bundle}/{uuid} ordering, which is helpful but largely mirrors 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 ('Delete a resource by UUID') plus the exact JSON:API endpoint, so the operation is unambiguous against create/get/update/list siblings. It doesn't explicitly differentiate itself from siblings, but 'delete' is inherently distinct in the naming.

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

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

Usage is implied by the verb — the agent knows deletion happens here — but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives (e.g., drupal_update_resource vs delete). No prerequisites such as required permissions are mentioned.

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 reinforces this with the JSON:API GET mapping but adds nothing about failure modes (404 on unknown UUID, 403 permissions), include-related errors, or response shape — modest added value over 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?

Two tight sentences, front-loaded with the core action and scope, followed by the concrete HTTP endpoint for agents that reason about JSON:API. 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 read-only single-entity fetch with 100% schema coverage and no output schema, the description plus the JSON:API endpoint reference is nearly sufficient — an agent can infer standard JSON:API document output. Only error/empty-result behavior is left unspecified.

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 are already documented in-schema, including that 'include' is a comma-separated path list. The description only restates that includes are optional, adding no meaning beyond the schema — baseline 3 is 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?

States a specific verb and resource ('Get a single resource by UUID for an entity_type/bundle'), and the word 'single' cleanly separates it from the sibling drupal_list_resources / drupal_search_content. The appended JSON:API path pins down exactly what is being fetched.

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

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

Usage is only implied: the UUID-based signature signals 'retrieve a known entity', which steers an agent away from list/search tools. However, no alternatives are named and there is no explicit when-to-use vs. drupal_list_resources or drupal_search_content 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 establish readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the JSON:API endpoint it targets (GET /jsonapi/{entity_type}/{bundle}) and the real constraint that filtering is limited to a *single* field, which an agent could easily miss.

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, capability summary first and API mapping second, with no filler. Every clause carries information the agent can act on.

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 a readOnlyHint annotation, the description covers scope, capability set, and the underlying endpoint. Return shape and paging defaults are secondary for a tool whose safety profile is already declared and whose parameters are fully documented.

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 in the schema, including the query-param mappings and defaults. The description only restates the categories (sorting, pagination, includes, single-field filter) without adding 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 (list) and resource (a collection of resources) scoped to an entity_type/bundle, and enumerates the supported capabilities. It implicitly separates itself from drupal_get_resource (single item) via 'collection', but never names the closest alternative, drupal_search_content, so the 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?

The description implies when this tool applies (listing a bundle's resources with sort/paging/filter), but gives no explicit when-to-use or when-not guidance and never routes the agent to drupal_search_content for cross-bundle or full-text lookups. 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 establishes the safe-read profile, and the description adds the concrete discovery endpoint (GET /jsonapi) and the shape of what comes back (types with hrefs) — useful context beyond the annotation. No pagination or rate-limit notes, but there is little additional risk surface for a type index.

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 returns and followed by the reason to use it. Every clause earns its place with no redundancy.

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

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

For a no-argument discovery endpoint with no output schema, the description covers purpose, returned content, and the underlying endpoint. It does not describe the response structure in depth, but with no output schema and trivial complexity that omission is minor.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline this lands at 4. No parameter syntax is needed or missing.

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 available JSON:API resource types') and clarifies the returned unit as entity_type/bundle pairs with hrefs. The discovery framing ('so the agent can discover what to query') cleanly separates it from the sibling drupal_list_resources, which lists actual content rather than the type index.

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?

'So the agent can discover what to query' gives a clear context for when to reach for this tool: ahead of content queries. It stops short of naming explicit alternatives or when-not conditions, so it is clear context without full 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?

readOnlyHint=true already establishes the safety profile, so the description's main added value is behavioral scope: matching is restricted to node titles via CONTAINS, not full-text search, and it maps to a JSON:API GET. It says nothing about authorization, result ordering, or how many results come back by default, leaving those to the schema and 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?

Two tightly packed sentences with the purpose front-loaded and no filler. The trailing 'JSON:API: GET /jsonapi/node/{bundle} with a verbose CONTAINS filter on title' is implementation detail that slightly exceeds what an agent needs to invoke the tool, but it is compact and earns its place as scoping 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?

With no output schema, the description does carry the burden of saying what comes back, and it does state at a high level that it returns nodes (of a bundle). Combined with full schema coverage and a read-only annotation, this is nearly enough, though it could say more about the returned node shape and default result count.

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 three parameters are already documented, including query as a CONTAINS match on title and bundle as the content-type machine name. The description restates the title-CONTAINS semantics rather than adding format or syntax detail beyond 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 ('list nodes of a bundle whose title CONTAINS a query string'), which clearly separates it from generic listing or fetching by ID. The 'convenience node-title search' framing hints at its relationship to drupal_list_resources, but no sibling is named explicitly, 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 word 'convenience' and the title-only CONTAINS scope imply when this is useful, but there is no explicit 'use this instead of X' or a stated exclusion (e.g. that it does not search body text). Usage must be inferred from the mechanism described.

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 supply only destructiveHint=true, so the description carries most of the burden and does add real value: the PATCH endpoint, the exact request body shape, and the semantics that only supplied attributes/relationships change while others are left untouched. It still omits permission/revision or validation-failure behavior, which a mutation tool ideally discloses.

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: the operation first, then the endpoint, then the body contract. Nothing is wasted 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 a five-parameter mutation tool with no output schema and minimal annotations, the description covers the endpoint and payload contract adequately. The remaining gap is failure-mode and permission behavior, which is minor given the body contract is fully spelled out.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by showing how uuid/bundle/entity_type compose the URL and how attributes and relationships nest inside the { data: { type, id, attributes?, relationships? } } body.

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 (update), resource (existing resource identified by UUID), and scope (partial update of attributes and/or relationships). This naturally separates it from the create/delete/get/list siblings without opening their schemas.

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

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

The partial-update qualifier implies when this is preferred over a full replace, and the UUID requirement implies the caller must already know the entity. However, it never names an alternative tool or states an explicit when-not condition, so routing guidance is only implied.

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