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

With no annotations, the description carries the burden and does useful work: it discloses the SLUG_EXISTS failure mode and the non-obvious upsert behavior that a done todo with the same slug gets replaced. It still omits auth/permission needs, pagination, and the return shape, but the edge-case semantics are the highest-value disclosure here.

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, no filler, with the core action front-loaded and the failure/replacement caveat immediately after. Every clause earns its place.

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

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

For a 4-param create tool with no annotations and no output schema, the description covers the action plus the two behavioral surprises an agent would otherwise get wrong. It could still say more about the optional date/importance fields' effect, but nothing critical 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?

Schema description coverage is 75% and the schema documents all four parameters, including date formats and slug pattern. The description adds no parameter-level meaning beyond restating slug uniqueness, 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?

Specific verb+resource ("Create a todo") plus slug-based identity, which clearly separates it from read-oriented siblings like todo_list and todo_search. It doesn't explicitly name a sibling (e.g., todo_update) to route away from, so it falls short of 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?

Says nothing about when to choose this over todo_update (which likely also modifies todos) or whether to check todo_search first. The SLUG_EXISTS note hints at a precondition but is framed as an error, not as usage 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 destructiveHint=true, so the safety profile is covered. The description still adds real value by stating the deletion is permanent/irreversible and applies to todos in any state, which goes beyond the bare annotation. It says nothing about confirmation requirements, dependent items, or error 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?

A single short sentence with the action verb front-loaded and no filler. It is efficiently sized, though it is terse enough that the scope qualifier carries a lot of weight on its own.

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

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

For a simple one-parameter delete with destructiveHint coverage and no output schema, the essentials (permanent, any state) are conveyed. It stops short of describing side effects such as removal of nested/sub-items or whether the action is hard-deletion vs archival, which an agent invoking a destructive tool would benefit from.

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 0% and the single required parameter 'slug' has only a pattern and maxLength constraint, no meaningful description. The description offers no information about what the identifier refers to or where it comes from, so it does not compensate for the schema gap.

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 ('Permanently delete a todo') and adds scope with 'open or done', which usefully clarifies that state does not gate deletion. It does not explicitly name the sibling it contrasts with (todo_done / todo_update), so identification is clear but not sibling-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?

The word 'permanently' implicitly contrasts with todo_done (mark complete) and the 'open or done' phrase implies deletion works regardless of state, so usage is inferable. However, no explicit when-to-use/when-not guidance or named alternative is provided.

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 idempotentHint=true; the description goes further by concretely explaining the no-op semantics on an already-done todo and naming the response field already_done: true, which is valuable since no output schema exists. It still omits success-path return info or error 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 tight sentences with zero waste; the core action is front-loaded and the edge-case behavior follows immediately.

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

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

For a simple one-parameter mutation with no output schema, the description covers the key non-obvious behavior (idempotent no-op and the already_done flag). It could say more about the success response, but nothing critical 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?

Schema description coverage is 0% and the description says nothing about the 'slug' parameter, so it does not compensate for the gap. The parameter is a single obvious identifier whose format is documented by the schema pattern and maxLength, so the omission is not severe.

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

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

The description states a specific verb+resource ('Mark a todo as done'), which is clearly distinguishable from siblings like todo_add and todo_delete. However, it does not explicitly differentiate from todo_update, which could plausibly also change a todo's state.

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 use case is implied by the name and first sentence, and the description notes the already-done case is harmless, but there is no explicit guidance on when to prefer this over todo_update or other siblings, nor any stated 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?

readOnlyHint=true already declares the safety profile, so the bar is lower, and the description does add real behavioral detail about ordering (undated last, high importance first). It omits the significant default that only open todos are returned, plus any mention of the limit/pagination 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?

A single front-loaded sentence with zero waste; the most surprising rule (undated last) leads. Nothing to trim.

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 read tool with no output schema, the description covers sorting but not the default open-only filter or the 50-item limit, both of which materially affect what an agent gets back. Adequate but with clear gaps.

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

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

Schema coverage is 60%, with enums carrying their own inline descriptions for order, range, and importance. The description adds ordering meaning the schema lacks (the "order" param only says "Date order"), but says nothing about the status default or the limit parameter, leaving the filtering behavior undocumented.

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 ("todos") plus the sort semantics, so the action is unambiguous. However it never distinguishes itself from the sibling todo_search, which is the obvious ambiguity an agent would face here.

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 call todo_list versus todo_search, nor any mention of the default status filter that shapes the result set. Usage is only implied by the verb "List".

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 is consistent with a search operation, so the safety profile is already covered. The description adds matching semantics (case-insensitive, which fields are searched), but omits notable behavior: the default status filter of 'open' and any pagination/limit behavior, which materially affect results.

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

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

A single tight sentence with the key matching semantics front-loaded and no filler. Efficient, though it is arguably too spare given the undocumented parameters.

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, three parameters at 0% description coverage, and a non-obvious default status filter, the description leaves real gaps an agent needs before calling 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?

Schema description coverage is 0% across three parameters, so the description must compensate. It explains what 'query' matches against, which is genuinely useful, but says nothing about 'limit' or the 'status' enum whose default is 'open' — a filter that silently narrows results without the agent knowing.

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 (substring search) plus resource and match semantics (case-insensitive, over slugs and prompts), which is more than the bare name. It does not explicitly distinguish itself from the sibling todo_list, 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?

No guidance on when to use this versus todo_list or when a substring search is preferable to listing. The only implied usage is 'you have a query string', with no exclusions or alternatives named.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses two facts not covered by the schema: updates are partial (unspecified fields are preserved) and the slug is immutable. It omits error behavior, whether updates are idempotent, and what happens when the slug does not match an existing todo.

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, each doing distinct work: stating the operation and scope, defining patch behavior, and flagging the immutable field. The most important constraint (partial update) is front-loaded and there is 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?

For a four-parameter mutation tool with no annotations and no output schema, the description covers the essentials of update semantics and the slug constraint, which is adequate. It still leaves gaps around prompt and importance handling, invalid-slug outcomes, and return behavior, so it is only minimally sufficient.

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 only 50%: date is richly documented in the schema, but prompt and importance have no descriptions anywhere, and the tool description adds nothing about them. The description does contribute one parameter-level fact (slug immutability), so it adds some value but does not compensate for the undocumented fields.

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 ("Update an existing todo") and adds scope with "open or done," so the agent knows this handles both completion states rather than only pending items. It does not explicitly distinguish itself from siblings like todo_done, which appears to overlap, 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?

"Only the fields you pass change" communicates patch semantics, which tells the agent it can send partial updates, and "The slug cannot be changed" flags a constraint. However, there is no explicit routing guidance such as when to use this versus todo_done for marking completion, leaving the alternative selection implied.

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