Castle MCP by usefulapi

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

Annotations only declare destructiveHint=true; the description adds the critical qualifier that the operation is reversible via castle_unarchive_list_item, which materially softens how an agent should treat the destructive flag. No detail on permissions or whether archived items persist in other views, but the key side effect is disclosed.

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

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

Three short sentences, front-loaded with the action and effect, then the reversal path. The trailing REST endpoint mapping is mildly redundant for an MCP caller but is compact and does not bloat the definition.

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

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

For a two-parameter, fully schema-documented mutation tool with annotations present and no output schema, the description covers what it does, its effect, and how to undo it. Only error/permission behavior is left unaddressed, which is a minor gap.

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

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

Schema description coverage is 100% and both parameters (list_id, item_id) are documented there, so the description is not required to carry parameter meaning. It adds nothing extra about the parameters, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Archive a list entry') and adds the functional effect ('so it stops matching'), which goes beyond restating the name. It also distinguishes itself from the sibling castle_unarchive_list_item by naming the inverse 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?

Gives a clear usage context (use it to make an item stop matching) and names the alternative path (unarchive for reversal). There is no explicit when-not-to-use guidance, e.g. archive vs. update or archive vs. delete, but the context is unambiguous.

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 declares the safety profile, but the description adds a genuinely useful fact the annotation cannot convey: the underlying Castle call is a POST, so an agent should not infer a mutation from the HTTP verb. It also names the concrete endpoint. No return format or pagination notes, but those matter little for a count.

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 and scoping, followed by the read-only clarification and endpoint. Nothing is padded.

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

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

For a two-parameter count tool with no output schema there is little else an agent needs: it knows what is counted, on which list, with which filters, and that the call is safe. The only residual gap is that filter operator semantics are deferred to the sibling search tool rather than 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 list_id and filters are already documented in the schema. The description's note that filters mirror "the search" adds marginal routing value but no new syntax or field/op semantics beyond the schema. 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 (count) and resource (entries in one list), and implicitly contrasts with the sibling that returns items rather than a count. An agent can distinguish this from castle_search_list_items without opening either schema.

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

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

"with the same optional filters as the search" implies when this is used (you want a count, not the item payloads), but there is no explicit when-to-use guidance or named alternative such as castle_search_list_items. Usage is implied 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?

Annotations already declare destructiveHint=true, and the description adds the meaningful detail that the list can be allow or deny and references the underlying POST /v1/lists endpoint. It does not explain what allow vs deny changes downstream, nor that creating a list is purely additive despite the destructive hint — a mildly confusing signal left unaddressed.

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

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

Three short sentences, front-loaded with the action and the key semantic field. The trailing 'Castle: POST /v1/lists' is low-value endpoint trivia but costs little.

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 creation tool with full schema coverage and no output schema, the description covers the essentials. It does not state what is returned (e.g., the new list ID) or whether the primary_field is immutable after creation, both of 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 description coverage is 100%, so all five parameters including name, color, and secondary_field are already documented. The description's explanation of primary_field ('the event field its entries match on') duplicates the schema text rather than adding syntax, allowed values, or 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 and resource ('Create a new allow or deny list') and clarifies that primary_field is the matching event field, which goes beyond the title. It never names or differentiates itself from siblings such as castle_create_list_item or castle_update_list, so the distinction rests on the tool name alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives like castle_update_list (for existing lists) or castle_create_list_item (for entries). The agent must infer from the name that this is the creation path.

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

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

Annotations only declare destructiveHint=true; the description earns credit by explaining why, stating 'This changes live policy behaviour,' which tells the agent the write has immediate enforcement impact rather than being an inert data edit. It still omits auth requirements, duplicate-handling/idempotency, and reversibility, so it is not fully transparent.

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 plus the endpoint reference, with the action front-loaded and the impact warning immediately after. No sentence is wasted and there is no 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 mutation tool with no output schema, the description covers purpose, concrete use case, live-policy impact, and the backing endpoint, and the schema fully documents parameters. What remains uncovered is duplicate entries, error conditions (e.g. value not matching the list's primary_field), and the response shape.

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, so the baseline is 3. The description adds only the endpoint hint (POST /v1/lists/{list_id}/items) and no extra meaning for required fields such as author_type, author_identifier, or the primary/secondary value pairing.

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

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

The description gives a specific verb and resource ('Add an entry to a list') and reinforces intent with a concrete example ('block an IP or an email'), which makes the operation unambiguous. It does not, however, explicitly contrast itself with nearest siblings like castle_create_list or castle_update_list_item, so it falls just short of the top band.

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 example ('block an IP or an email') implies the usage context, but there is no explicit when-to-use or when-not-to-use statement and no named alternative among the many list-related siblings. An agent can infer intent, but the routing guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that this is a prerequisite discovery step and summarizes what comes back (field names plus types), which is meaningful 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?

Two short sentences with the purpose front-loaded and the usage directive second; the endpoint is appended without bloating the text. No sentence 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 no-parameter, no-output-schema discovery tool, the description tells the agent exactly what it returns (filterable/groupable field names and types) and why to call it first, which is everything needed to invoke it correctly.

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

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

Zero parameters, so per the rubric the baseline is 4. Nothing in the description needs to compensate for parameter documentation.

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

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

States a specific verb and resource ('List the event fields you can filter and group on, with their types'), plus the API endpoint it maps to. It also distinguishes itself from the sibling query tools by framing itself as the prerequisite for them.

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

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

'Read this first — the other query tools need real field names' gives explicit ordering guidance pointing at castle_search_events and castle_group_events. It doesn't name a when-not condition, but the when-to-use is unambiguous.

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 tells the agent this is a non-mutating read, so the bar is lower. The description usefully adds that the response carries field definitions (primary and secondary), which is genuine behavioral context the annotations do not provide, but it says nothing about auth scope, error behavior, or whether deleted/archived lists are 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?

Two short sentences, front-loaded with the operation and its payload, followed by an endpoint reference. No filler or 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?

With no output schema, the description does the right thing by sketching the response shape (field definitions), and a one-param read tool needs little else. It stops short of describing the full returned structure or error cases, but is adequate for correct invocation.

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 parameter, so the schema already documents list_id; the description's '/v1/lists/{id}' path merely restates it. Baseline 3 is appropriate when the schema does all 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 (fetch), a specific resource (a single list), and what the payload contains (primary and secondary field definitions), plus the underlying REST endpoint. It implicitly distinguishes itself from castle_search_lists by being an id-based single-item retrieval, though it never names the sibling explicitly.

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

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

The description implies the usage context (retrieve one list by id) but gives no explicit when-to-use guidance, no statement of when to prefer castle_search_lists instead, and no prerequisites or error conditions (e.g. what happens for an unknown or archived list id).

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's marginal contribution is the enumerated return fields and the REST endpoint mapping. It adds no auth, pagination, or not-found behavior — adequate but thin given the lower bar set by 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?

A single front-loaded sentence that names what is fetched and what comes back, followed by a compact endpoint reference. No filler whatsoever.

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

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

For a two-parameter read with no output schema, the description compensates by naming the returned fields, which is genuinely useful. It stops short of describing error behavior (e.g. item not found) or response shape details.

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; baseline 3 applies. The path template shows how list_id and item_id map onto the endpoint, which is marginal added value but no format or constraint detail.

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 (fetch) and resource (a single list entry), and even enumerates the fields returned (value, adder, comment, archive time). 'Single' implicitly distinguishes it from the sibling search_list_items and count_list_items.

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 required list_id/item_id pair signals 'use when you already know the exact item', but the description never states when to prefer it over castle_search_list_items or castle_get_list. No exclusions or prerequisites are given.

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

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

The annotations already declare readOnlyHint=true, and the description reinforces this with the useful clarification 'Read-only despite being a POST' — a genuinely helpful note that prevents an agent from avoiding the tool out of write-operation caution. It stops short of describing pagination or result 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 tight sentences: purpose and use case first, then the read-only clarification and endpoint. No filler, and the most decision-relevant facts are 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?

With readOnlyHint covering the safety profile and full schema coverage of all four parameters, the definition is nearly self-sufficient. The one remaining gap is that no output schema exists and the description does not characterize the aggregated result shape, though the grouping semantics imply 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%, so the schema fully documents filters, group_by_fields, page and results_size, including operator lists. The description adds no parameter-level meaning beyond restating that grouping takes 'one or more fields,' 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: 'Aggregate matching events by one or more fields,' and names the grouping mechanism. It distinguishes itself conceptually from castle_search_events (aggregation vs. listing) but never names that sibling explicitly.

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

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

'the fast way to see which IPs, devices or countries dominate a spike' gives a concrete use case, which implies when the tool is appropriate. However, it never states when NOT to use it or names castle_search_events as the alternative for raw event retrieval, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true, but the description adds genuinely useful context beyond them by resolving the tension the agent would otherwise hit: 'Read-only despite being a POST: Castle takes the query in the body.' It also names the concrete endpoint POST /v1/events/query. Pagination limits and rate-limit behavior are still unaddressed.

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

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

Two sentences, zero filler, with the purpose front-loaded and the read-only/POST clarification following. The endpoint reference is compact and useful rather than redundant 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 5-parameter search tool with 100% schema coverage and no output schema, the description covers purpose, read semantics and transport. It does not explain ordering, default page size or result-shape expectations, but the description is not obligated to cover return values here.

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 filters, columns, page, results_size and query_type thoroughly, including the operator list and the pointer to castle_get_events_schema. The description adds no parameter-level meaning on top of that, so the 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 — 'Query the security event stream' — and enumerates the payload ('logins, registrations, transactions and their risk verdicts'), so an agent knows exactly what comes back. It does not, however, differentiate itself from the aggregation sibling castle_group_events, which also targets the event stream.

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 resource ('search security events') but there is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as castle_group_events for aggregated views. The instruction to call castle_get_events_schema first lives in the schema, not the description, so the description itself routes nothing.

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, but the description adds genuinely useful context by preempting the HTTP-method confusion: 'Read-only despite being a POST.' It also exposes the underlying REST route, which helps an agent map intent to the API. It stops short of describing pagination behavior or result limits beyond what the schema carries.

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 tightly packed sentence plus a short clarifier and the route. Nothing is redundant and the resource scope is front-loaded before the method caveat.

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 filtered-list tool with a fully documented schema and no output schema, the definition covers purpose, scope and the POST/read-only nuance. The only minor gap is pagination/return-shape guidance, which the schema's page and results_size parameters largely imply.

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 page, results_size, filters and list_id are already documented in the schema with ranges and semantics. The description adds only the resource framing ('entries of one list') and no extra syntax or format detail, so the baseline of 3 applies.

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

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

States a specific verb (search) and resource (entries of one list), and clarifies the resource scope by enumerating what a list holds (blocked IPs, emails, device ids). This cleanly distinguishes it from the sibling castle_search_lists, which searches the lists themselves rather than their entries.

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

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

The description implies usage (query the items inside a given list) and the required list_id makes the scope explicit, but it never states when to prefer this over castle_get_list_item or castle_count_list_items, nor any prerequisites. Usage is inferable rather than spelled out.

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, but the description adds genuinely useful context the annotations cannot convey: that the transport is a POST (via 'POST /v1/lists/query') yet the operation is non-mutating. That is exactly the kind of trap an agent could otherwise fall into. It does not discuss pagination behavior, but the schema covers page/results_size.

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 the core purpose front-loaded and the non-obvious safety note immediately after. Every clause earns its place; nothing is 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 3-parameter, all-optional read tool with no output schema, the description covers purpose, transport, and mutation safety. The only residual gap is what a result looks like and how filtering narrows results, which the schema partially handles anyway.

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% – page, filters, and results_size each carry their own documented semantics, including the {field, op, value} filter shape. The description adds nothing beyond this, so the baseline of 3 applies.

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

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

States a specific verb ('Find') and resource ('allow/deny lists defined in the environment'), and the resource granularity (lists, not items) implicitly separates it from castle_search_list_items and castle_get_list. It stops short of naming a sibling or an exclusion, so it is clear rather than maximally disambiguating.

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 agent can infer this is for locating lists when the exact list ID is unknown, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as castle_get_list for known IDs.

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 contributes some value by naming the restore semantics ('so it matches again'). However it says nothing about idempotency, permissions, or what happens if the item was not archived; the raw endpoint string is developer detail rather than agent-relevant 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 the action and scope front-loaded and no filler. The trailing endpoint reference is marginally useful but not essential for an agent, keeping it just short of a 5.

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-required-parameter mutation with no output schema, the description covers the action and target adequately. It would be complete with one line on idempotency or the archived-state precondition.

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

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

Schema coverage is 100% and both parameters already carry descriptions ('The item to restore.', 'The list holding the item.'), so the schema does the heavy lifting. The description adds no syntax, format, or ID-shape guidance beyond the path template.

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 ('Restore') and resource ('a previously archived list entry'), and the phrase 'previously archived' implicitly contrasts it with castle_archive_list_item. Minor terminology drift between 'list item' (name/title) and 'list entry' (description) keeps it 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 implicit precondition ('previously archived') hints at when this applies, but the description never states when to choose it over siblings like castle_update_list_item or castle_archive_list_item, nor any exclusions. Usage is only implied.

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 flag this as destructive (destructiveHint=true), so the mutation risk is covered by structured data. The description adds nothing behavioral beyond that: it does not say whether omitted fields are preserved or nulled (a real concern given PUT semantics), nor whether permissions or ownership are required. Naming the HTTP method is not behavioral disclosure.

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

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

Two short sentences, front-loaded with the action and with the endpoint detail trailing. Nothing is padded, though the endpoint note is marginally redundant and the second sentence could carry more value.

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

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

With 4 parameters at full schema coverage and no output schema, the parameter side is adequately covered by structured data. However, for a destructive update the description never resolves whether this is a partial or full replacement, leaving an agent to guess at the effect on fields it does not send.

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 every parameter (name, color, description, list_id) is already documented in the schema. The description restates the same three updatable fields without adding format, constraints, or interaction rules, so the 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 set (rename/change) applied to a named resource (a list), and the fields affected are enumerated, so it is distinguishable from castle_update_list_item and castle_create_list by name and resource. It stops short of explicitly naming the sibling it differs from, but the resource-level distinction is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of any alternative tool. The endpoint hint (PUT /v1/lists/{id}) tells the agent where the call goes but not when to prefer it over create_list, get_list, or update_list_item.

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, so the mutation profile is covered structurally. The description adds only the REST endpoint mapping (PUT /v1/lists/{list_id}/items/{id}), and says nothing about permissions, whether the prior comment is overwritten, 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?

Two short sentences with the action front-loaded and the API mapping secondary; no filler or 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 simple three-parameter, fully-required mutation with no output schema, the description covers the core action adequately. It nevertheless omits behavior an agent would want before calling a destructiveHint tool, such as whether the comment is fully replaced and what a successful response contains.

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

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

Schema description coverage is 100% and all three parameters are documented (comment, item_id, list_id), so the schema carries parameter meaning. The description adds nothing beyond the schema's own wording, which is the expected baseline when coverage is complete.

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 ('Change the comment on a list entry'), which is clearly distinct from sibling mutators like castle_update_list. However, it does not explicitly contrast itself with castle_update_list or castle_archive_list_item, so sibling differentiation rests on the name alone.

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

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

There is no statement of when to use this tool versus alternatives such as castle_update_list, nor any prerequisites (e.g., the item must already exist, or that the previous comment is replaced). The only usage cue is the implied meaning of 'Change'.

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