castle

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

Annotations supply only destructiveHint=true; the description adds the crucial nuance that the state change is reversible via a specific sibling, and reveals the underlying DELETE endpoint. It does not cover permissions or side effects on list search/matching counts, so it is strong but not exhaustive.

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, zero filler: purpose and effect first, reversibility second, endpoint reference last. Nothing is buried and nothing is repeated from the title beyond what adds 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?

For a two-parameter mutation with no output schema and only a destructiveHint annotation, the description supplies the essential missing context (what changes, how to undo it). Minor gaps remain on required permissions and downstream effects, but nothing blocks 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?

With 100% schema description coverage on both parameters, the schema already documents list_id and item_id fully. The description adds no format, ID-source, or constraint detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (archive) and resource (a list entry), plus the observable effect ('so it stops matching'), which distinguishes it from delete/update siblings. It also names the exact inverse tool, castle_unarchive_list_item, so the agent can place it precisely in the tool family.

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

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

It gives real routing guidance by naming the counterpart tool that undoes the operation, making the archive/unarchive pair unambiguous. It stops short of an explicit when-not clause (e.g., why archive instead of delete or update), so it is clear context rather than full when/when-not coverage.

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: it warns that the operation is read-only despite being a POST, which resolves an apparent HTTP-verb/semantics mismatch an agent would otherwise misread as a mutation. No rate limits or return-shape details are given, but the annotations carry the safety profile.

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 purpose and filter behavior, followed by the read-only caveat and the endpoint. Nothing is padded and 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 two-parameter count tool with no output schema and full schema coverage, the description plus annotations give an agent everything needed to call it correctly. The only minor omission is that it never states the return value is a scalar count, though that is largely self-evident from the name.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by telling the agent that filters follow the same semantics as the search tool's filters, which the schema's generic '{field, op, value}' wording does not convey. It does not elaborate on filter fields or operators itself.

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: count the entries in one list. The word 'Count' clearly separates it from sibling castle_search_list_items, which returns the items themselves, and from castle_get_list, which returns list metadata. It does not name a sibling explicitly, 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?

The phrase 'with the same optional filters as the search' implies this is a lightweight count-only alternative to castle_search_list_items, which is a usable routing hint. However, there is no explicit when-to-use vs when-to-call-search statement and no exclusions or prerequisites.

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

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

Annotations already declare destructiveHint=true, so the write/mutation profile is partly covered, though the description never mentions the destructive/irreversible nature of creating a list itself. It does add useful context about what a list is (allow/deny, entries matched on a primary field) and the underlying endpoint POST /v1/lists, but says nothing about duplicate-name handling, limits, 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?

Three short, front-loaded sentences with no filler; the core purpose leads. The middle sentence largely duplicates the schema description of primary_field, which is mild redundancy, and the endpoint clause is arguably the least useful part.

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 creation tool with no output schema, the description covers purpose and one key field but omits what a caller gets back (e.g. the list ID needed for subsequent castle_create_list_item calls) and any error/duplicate behavior. Adequate but with clear gaps for an agent chaining create-then-populate workflows.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including primary_field verbatim. The description's primary_field sentence is essentially a restatement of the schema text, and it adds nothing about color, name, description, or secondary_field. 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 ('Create a new allow or deny list') and even narrows the list types, so an agent can tell it apart from castle_update_list, castle_get_list, and castle_create_list_item. It stops short of explicitly naming those siblings, so it is clear but not maximally differentiated.

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

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

There is no when-to-use guidance and no routing away from alternatives: nothing says when to create a new list versus adding an item with castle_create_list_item, updating with castle_update_list, or searching with castle_search_lists. Usage is only implied by the verb 'Create'.

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 provide destructiveHint=true, so the description adds real value by clarifying that the action 'changes live policy behaviour' and by naming the underlying endpoint. It still omits auth requirements, rate limits, and any indication of reversibility or response behavior.

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

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

Three tight sentences, front-loaded with the action, and each sentence earns its place by adding scope, consequence, or endpoint detail. 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 mutation tool with minimal annotations and no output schema, the description covers the essential 'what' and the key consequence of the write. It stops short of covering permissions or return information, which is a modest gap rather than a critical one.

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 every one of the 7 parameters is already documented in the schema (including required/optional and the author_type enum). The description adds only the endpoint path, which lightly implies list_id's role; 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+resource ('Add an entry to a list') and grounds it with concrete examples (block an IP or an email), so the function is unambiguous. It implicitly separates itself from siblings like update/archive_list_item, but never names an alternative, so it falls short of full sibling 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?

Gives clear usage context via the blocking example and flags that this alters live policy, which tells the agent when this is the right action. It offers no explicit when-not or alternative-tool guidance (e.g., when to use update_list_item instead).

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 establishes that this is a safe read operation, so the bar is lower. The description adds that the output is a list of field names and types, but does not disclose anything further about behavior (e.g., auth, caching, response format) beyond the annotation.

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

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

Three short, front-loaded sentences with no waste. The key instruction ('Read this first') is placed where it will be seen immediately, and the endpoint note is a compact suffix.

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

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

For a zero-parameter, read-only schema-discovery tool with no output schema, the description is complete: it states what is returned (field names and types) and the role it plays relative to the query tools. Nothing needed to call it correctly is missing.

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

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

There are zero parameters, so the baseline is 4 per the rubric. The description adds no parameter detail because none exists, which 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 first sentence states a specific verb (List) and resource (event fields you can filter and group on) plus what is returned (their types). This clearly distinguishes it from the query siblings like castle_search_events and castle_group_events, which consume the schema rather than describe it.

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

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

It explicitly tells the agent when to use it: 'Read this first — the other query tools need real field names.' This is a clear directive tied to a concrete prerequisite for the sibling query tools, leaving no ambiguity about ordering.

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 agent knows this is a non-mutating read. The description adds that the response includes primary and secondary field definitions, which is useful context beyond the annotations, but it omits error behavior for a missing/invalid list_id and any auth or rate-limit notes.

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 the returned content. The trailing 'Castle: GET /v1/lists/{id}' is a useful API mapping, though it slightly duplicates the schema's required list_id.

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

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

For a single-parameter read tool with no output schema and readOnlyHint annotations, the description covers what it does and what the response contains. It would be fully complete with a note on missing-id behavior or how it relates to search_list/count siblings.

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

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

Schema description coverage is 100% with only one parameter ('list_id'), and the schema already documents it as 'The list's id.' The description adds nothing param-specific beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Fetch a single list') and adds scope about what is returned ('primary and secondary field definitions'), which is more specific than the bare title. It does not explicitly differentiate from siblings like castle_search_lists or castle_get_list_item, so the sibling-confusion gap 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 description gives no when-to-use guidance, no prerequisites, and does not mention alternatives such as castle_search_lists for discovery or castle_get_list_item for items. An agent must infer usage 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.

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

Annotations only declare readOnlyHint=true, so the description usefully adds what comes back (value, who added it, the comment, its archive time) and identifies the underlying endpoint. It doesn't discuss permissions, rate limits, or behavior on missing/archived items, but for a safe read this is solid added 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 sentence of purpose and return fields followed by the endpoint mapping; nothing is redundant and the verb leads the 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?

With no output schema, the description compensates by enumerating the returned fields, and the read-only nature is covered by annotations. It is nearly complete, with only edge-case behavior (not found, archived items) left unaddressed.

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 list_id and item_id are already documented in the schema. The description adds no format, ID-source, or lookup details beyond that, 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 ('Fetch a single list entry') and enumerates the returned payload (value, author, comment, archive time), which clearly separates it from search_list_items and count_list_items by scope. It stops short of naming any sibling explicitly, so it sits at clear-but-not-differentiating-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 phrase 'a single list entry' implies this is for direct ID lookup rather than searching, but there is no explicit when-to-use / when-not-to-use statement and no routing to search_list_items as the alternative when the item_id is unknown.

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 readOnlyHint, and the description usefully resolves the mismatch by stating 'Read-only despite being a POST' — exactly the kind of context an agent needs when the HTTP verb would otherwise imply mutation. It does not cover pagination limits or result-size behavior, but the route hint (POST /v1/events/group) adds traceability.

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: the purpose/benefit first, then the behavioral caveat and endpoint. No filler, nothing 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?

With no output schema, the description could say more about the shape of the aggregation result, but it does establish the read-only nature, the endpoint, and the schema prerequisite. Adequate for a 4-parameter aggregation tool.

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 filters, group_by_fields, page and results_size are all documented in the schema itself. The description adds no syntax or semantics beyond a generic mention of grouping, 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 (aggregate/group) and resource (matching security events) plus the grouping fields involved, so the operation is unambiguous. It does not name a sibling for contrast, but 'aggregate' versus a search/list tool is self-evident.

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

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

Gives a clear motivating context — 'the fast way to see which IPs, devices or countries dominate a spike' — and a concrete prerequisite ('Call castle_get_events_schema first'). It stops short of naming an explicit alternative such as castle_search_events for when grouping is not wanted.

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 resolving the apparent conflict that a POST is used for a read ('Castle takes the query in the body'). It does not discuss pagination behavior or result caps, which are left to the schema.

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 resource and its contents, followed by the read-only/POST clarification and the endpoint. No wasted text.

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 query tool with no output schema, the description covers what is being queried and why a POST is safe. It omits result-shape and pagination expectations, though the schema's results_size and page fields partially cover those.

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 filters, operators, query_type and paging are already fully documented in the schema. The description adds no parameter-level detail beyond the endpoint path, 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 ('Query the security event stream') and enumerates the content returned (logins, registrations, transactions and their risk verdicts). It does not explicitly distinguish itself from the sibling castle_group_events, which is the nearest alternative, so it falls 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?

The description gives no when-to-use guidance and never names an alternative such as castle_group_events. The useful hint about calling castle_get_events_schema first lives in the schema, not the description, so the description itself provides no routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the bar is lowered, but the description adds real value by stating 'Read-only despite being a POST' — resolving the exact confusion a POST endpoint would create. It also cites the underlying HTTP route. It does not, however, discuss pagination behavior or filter semantics.

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: scope first, then the read-only clarification and endpoint. Every clause earns its place with no filler.

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

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

No output schema exists, so return values need not be explained, and pagination/filters live in the schema. Combined with the read-only POST warning and endpoint, the definition is nearly complete; only filter behavior on nested objects is left unaddressed.

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 all four parameters (list_id, page, filters, results_size) are already documented in the schema; baseline is 3. The description occasionally hints at content ('blocked IPs, emails or device ids') but adds no new parameter syntax or format 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?

Names a specific verb (search) and resource (entries of one list), and clarifies what the list contains (blocked IPs, emails, device ids). This disambiguates it from siblings like castle_count_list_items, castle_get_list_item, and castle_search_lists 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 phrase 'Search the entries of one list' implies the usage context but gives no explicit when-to-use guidance or alternatives (e.g., count vs. get item vs. search lists). An agent must infer the routing from sibling names.

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 earns extra credit by disambiguating the counterintuitive transport ('Read-only despite being a POST') and citing the underlying endpoint. It does not address pagination or result-size behavior, but the schema covers those parameters.

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

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

Two short, front-loaded sentences with zero filler; the purpose comes first and the read-only caveat follows as supporting 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 zero-required-parameter search tool with full schema coverage and annotations covering the safety profile, the description supplies everything essential. Minor omissions, such as expected result shape or pagination semantics, are already handled by the schema or low-stakes.

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, filters, and results_size are already fully documented in the schema. The description adds no syntax or format detail beyond that, making the baseline 3 correct.

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

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

States a specific verb and resource ('Find the allow/deny lists defined in the environment'), which is clearly distinct from item-level siblings like castle_search_list_items and castle_get_list_item. It stops short of explicitly naming the sibling it is not, so it misses the top of the scale.

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

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

There is no when-to-use or when-not-to-use guidance and no mention of alternatives such as castle_get_list or castle_search_list_items. The agent must infer usage purely from the resource noun.

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. It adds the underlying HTTP operation (PUT /v1/lists/{list_id}/items/{id}/unarchive), which confirms this is an in-place mutation, but says nothing about idempotency, behavior on a non-archived item, or permission requirements.

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 followed by the endpoint mapping; nothing is wasted. Slight redundancy between the action sentence and the endpoint, but no bloat.

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-parameter mutation with no output schema, the description covers the essentials of what the tool does. However, with only a single destructiveHint annotation, it omits mutation-specific context an agent would want (state preconditions, side effects), leaving it adequate rather than complete.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so the baseline of 3 applies. The description restates the two path components (list_id, id) via the endpoint but adds no format or constraint 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 (restore/unarchive) and resource (a previously archived list entry), which cleanly distinguishes it from the sibling castle_archive_list_item. The trailing 'so it matches again' phrase is slightly vague but does not obscure the 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?

Usage is implied by 'restore a previously archived list entry' — the agent can infer this is for reversing an archive — but there is no explicit when-to-use guidance, no prerequisites (e.g. the item must currently be archived), and no named alternative among the siblings.

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

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

Annotations declare destructiveHint=true, but the description frames the operation as innocuous field edits and never reconciles that with destructiveness: it does not say whether omitted fields are cleared (PUT semantics), whether the change is reversible, or what permissions are needed. The mention of the PUT endpoint is genuine added context, hence not a 1.

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

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

Two short, front-loaded sentences with the actionable content first and the API mapping second; nothing is padded. The endpoint annotation is marginal but defensible for API-mapping purposes.

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 four-parameter update with full schema coverage and no output schema, the description is close to sufficient. The one materially missing piece is update semantics (partial vs. full replace and what happens to unspecified fields), which matters given destructiveHint=true; return values need not be described since no output schema exists.

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% (all four parameters are documented in the schema), so the baseline is 3. The description merely restates the same three editable fields (name, colour, description) and adds no syntax, format, or optionality 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?

The description names a specific verb set (rename / change colour / change description) and the resource (a list), and pins the underlying endpoint (PUT /v1/lists/{id}), so an agent knows exactly what it mutates. It does not explicitly contrast itself with the near-neighbour castle_update_list_item, but the resource noun plus the field list make the boundary 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?

There is no guidance on when to choose this over castle_update_list_item, castle_get_list, or castle_create_list, and no prerequisites (permissions, required existing list) are stated. Usage is only implied by the verb 'Rename... or change'. For a mutation tool sitting among 13 siblings, this is a gap.

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

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

Annotations already flag destructiveHint=true, but the description never says the existing comment is overwritten or unrecoverable, nor whether special permissions are needed. The 'PUT /v1/lists/{list_id}/items/{id}' line is API-routing trivia rather than behavioral context an agent can act on.

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

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

Two short sentences, front-loaded with the action and resource. The second sentence is endpoint mapping of marginal value but it is not bloated.

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 mutation with full schema coverage and no output schema, the description is minimally adequate. It still omits when to prefer it over sibling update tools and what happens to the previous comment, which matters given the destructive hint.

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

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

Schema description coverage is 100% and all three parameters are self-documenting ('The new comment.', 'The item to update.', 'The list holding the item.'). The description adds no syntax, format, or constraint detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Change the comment on a list entry.' The emphasis on 'comment' usefully narrows the otherwise broad name castle_update_list_item, distinguishing it from castle_update_list and castle_get_list_item. However, it does not explicitly contrast itself against 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 when-to-use guidance, no prerequisites, and no mention of alternatives such as castle_update_list or castle_create_list_item. The agent is left to infer that this tool changes only the comment field of an existing item.

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