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

With no annotations, the description carries the behavioral burden and does meaningful work: it states that existing tags are preserved, duplicates are skipped, and matching is limited to open to-dos. It could still mention what happens when no match is found, but the core behavior is 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?

The description is two compact sentences with the most important behavior front-loaded and the sibling contrast in a supporting second sentence. Every phrase 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 tag-adding mutation with complete schema coverage and an output schema available, the description provides the missing model-level information: merge semantics, no removal, and open-todo scoping. No critical selection or invocation information 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 100%, so the four parameters are already documented well. The description adds semantic context about merging and duplicate-skipping, but it does not need to restate parameter syntax or selection rules.

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 uses a specific verb ('Append') and a precise resource ('tags to the first matching OPEN to-do'), and immediately clarifies the non-replacing behavior. It also names update_todo, so an agent can distinguish this tool from its sibling that replaces tags.

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 contrasts this tool with update_todo(tags=...), telling the agent that adding/merging tags should use add_tags while replacing the whole tag set should use update_todo. That is a clear when/alternative rule rather than an implicit hint.

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?

With no annotations, the description takes on the full behavioral burden. It clearly states that cancellation is reversible, applies to open to-dos, and returns canceled task names. It could mention failure behavior or idempotency, but the key side-effect and reversibility are well 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?

The description is tight and front-loaded: the core verb and resource appear first, followed by targeted matching guidance, a use case, and return behavior. Every sentence contributes, and there is no repetition of schema fields or annotation data.

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?

Given this is a mutation tool with no annotations and no schema-property descriptions, the description covers purpose, reversibility, targeting, and the returned output. Still, it fails to define 'exact' behavior and the conflict for what happens when both the 'todo_id' and 'query' are supplied. These are important gaps for reliable 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?

The description names two parameters ('todo_id' and 'query') and says the matching rules are the same as complete_todo, which provides some meaning beyond the bare schema. With 0% schema-property coverage, though, the 'exact' parameter is not explained, and precedent behavior when both target args are supplied is left ambiguous. The description only partially compensates for the missing schema descriptions.

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 opens with a specific verb and resource: 'Mark open to-do(s) as canceled'. It also clarifies the semantic distinction from deleting by saying the operation is 'reversible' and should be preferred over deletion. This clearly differentiates it from other to-do state-change tools.

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 provides practical guidance: use it when a decision is rejected, and prefer it over deleting. It also points to 'same matching rules as complete_todo' for targeting context. However, it does not explicitly cover when not to use it, such as when the task should be completed instead of canceled.

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?

Since no annotations are provided, the description carries the full burden. It discloses that only OPEN to-dos are affected, that query matching is substring by default and exact when exact=True, and that the completed item names are returned for verification. It does not specify behavior when both todo_id and query are supplied, but the core mutating behavior is clearly visible.

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

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

The description is compact and well structured: action first, then targeting rules, then a return-value expectation. Every line adds useful information, and the line breaks make the parameter semantics easy to parse. No filler or repetition of schema-only facts.

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

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

The description covers the main behavior well and an output schema exists, but it leaves important boundary cases implicit. Specifically, with all three parameters optional and no required parameters, it never states what happens if neither todo_id nor query is provided, and it does not define precedence when both are given. An agent calling the tool with defaults could unintentionally match every open to-do.

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

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

The schema has no parameter descriptions, so this is entirely compensated by the tool description. It explains todo_id as the exact and safest target, query as a name match, and exact as controlling contains vs. exact matching with a default of false. All three parameters receive meaningful explanation beyond their type/default.

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 opens with 'Mark open to-do(s) as completed', which names a specific action and resource. It also distinguishes the tool by explaining the two targeting modes, making it clear how this relates to sibling tools such as cancel_todo or update_todo without confusion.

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 explicit decision guidance: use todo_id for exact and safest targeting, or query for name matching, and explains when to set exact=True versus False. It does not explicitly call out alternative sibling tools, but the parameter-selection guidance is clear and actionable.

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 burden of behavioral disclosure. It only says a to-do is created, but it does not mention what happens in the system, whether the new to-do lands in the Inbox unless area/project is supplied, whether duplicate creates are possible, or what failure conditions matter.

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?

This is a single focused, front-loaded sentence with no filler or repeated information. It is appropriately sized for a tool whose parameter details are already handled by a thorough 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?

For a create operation, the description plus a fully documented schema gives enough information to invoke the tool correctly. An output schema exists, so return-value explanation is not required. The main gap is usage context relative to sibling tools, which is not critical for successful 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 description coverage is 100% across all 7 parameters, so the baseline is 3. The description itself adds no parameter-level nuance, but it does not need to because the schema already explains defaults, precedence, date formats, and tag syntax.

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 clearly uses a specific verb ('Create') and names the exact resource ('a new Things 3 to-do'). The word 'new' distinguishes it from sibling tools like update_todo, complete_todo, and cancel_todo without any need to inspect 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?

There is no explicit guidance on when to use this tool versus alternatives. It does not mention that updates should go to update_todo, completion to complete_todo, or cancellation to cancel_todo, so the agent must infer usage context from the tool name and schema.

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 present, so the description carries the burden of behavioral disclosure. It is implicitly read-only ('List') and explains the Logbook scope and default lookback window, but it does not describe output ordering, tag filtering caveats, or other behavior beyond the core listing.

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 no filler. The primary purpose is front-loaded, and each sentence serves a distinct role: defining the core list operation and stating its intended usage 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?

Given a simple read tool with all parameters documented and an output schema present, the description is mostly complete. It could have explicitly differentiated itself from 'list_todos' or 'search_todos', but for the core operation it is adequate.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The only parameter-related mention in the description, the default of `days` to 30, duplicates what is already in the schema and adds no new information.

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 clearly states the action ('List to-dos completed within the last `days` days') and identifies the resource (completed to-dos) and source (Logbook). It does not explicitly mention sibling tools, but the 'completed' filter makes its scope distinguishable from generic list/search 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?

The sentence 'Useful for syncing finished tasks back into other systems' gives clear usage context for the tool. There is no explicit when-not-to-use guidance or mention of alternatives, which prevents a higher score.

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 must carry the full burden of behavioral disclosure. It adds the meaningful 'unfiled tasks' semantic but does not state whether this is a purely read-only operation, how results are ordered, whether pagination occurs, or what happens when no to-dos are present. The description communicates the purpose but not the 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?

The description is a single, tightly-crafted sentence that front-loads the verb and object and includes a useful parenthetical explanation. There is no fluff, repetition, or extraneous information.

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?

Given the simple interface with three optional, self-documented parameters and an existing output schema, the brief description is almost sufficient. It clearly identifies the resource and scope, but it could be slightly more complete by explicitly positioning itself against count of siblings such as list_todos and search_todos.

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 parameters (tag, limit, include_notes) are thoroughly described in the input schema. The tool description contributes no additional parameter-level meaning, so the schema is doing the heavy lifting. This meets the baseline for high schema coverage.

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

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

The description uses a specific verb ('List'), a precise resource ('all to-dos currently in the Things 3 Inbox'), and a clarifying parenthetical ('unfiled tasks') that distinguishes it from siblings like get_today, get_completed, and list_todos. It clearly identifies what the tool does and where its scope lies.

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 scoping phrase 'currently in the Inbox' implies when this tool should be used: whenever an agent needs unfiled or Inbox to-dos. However, it never explicitly names alternatives or defines when not to use it, leaving the selection guidance an unspecified baseline.

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?

With no annotations, the description carries the burden of behavioral disclosure. It clearly states that this is a read/list operation and that results are the currently-active Today list. It does not disclose ordering, pagination semantics, whether read-only guarantees exist, or how the Today list is defined beyond the name, so the transparency is only minimally adequate.

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

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

The description is a single direct sentence that front-loads action, scope, and list. It contains no filler, repetition, or redundant restating of the tool name.

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

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

For an uncomplicated read-only getter with zero required parameters, a high-coverage schema, and an output schema present, the description gives an agent enough to invoke it correctly. The minor gap is the lack of any sibling-comparison or ordering/behavior notes, which keeps it just shy of fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the main description adds no parameter detail of its own. The schema entries themselves are notably rich (tag filtering semantics, filtering before limit, notes payload size), but that credit belongs to the schema coverage, not to the tool description.

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 uses a specific verb and resource: "List all to-dos currently in the Things 3 'Today' list." It clearly identifies what is returned and scopes it to a particular list, which visually distinguishes it from siblings like list_todos, get_inbox, and get_completed.

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 main description gives no guidance about when to use this tool versus alternatives such as list_todos, search_todos, get_inbox, or get_completed. The only hint in the schema, suggesting get_todo() when notes are needed, is paramter-level advice and does not help an agent choose get_today among its 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?

The description explicitly states the key sentinel behavior: 'Returns null if it does not exist.' With no annotations available to carry read-only safety hints, the use of 'Get' also signals a non-destructive operation. This is sufficient additional behavioral transparency for such a simple getter.

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, purposeful sentences: the first defines the action and target, the second clarifies the return behavior for a missing ID. There is no repetition or filler, and the key information is properly 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?

Given a single parameter, a simple resource type, an output schema already available, and a short clear description that covers the null behavior, the tool definition contains everything an agent needs to correctly select and invoke it. Sibling tools add surrounding context without complicating this interaction.

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

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

The schema provides only a string type with 0% description coverage. The description compensates by explaining that the parameter is the Things to-do ID, adding meaning beyond the bare schema. Yet it does not mention how that ID is obtained or what string format is expected, leaving some room for further clarity.

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 clearly identifies a specific action and resource: 'Get a single to-do by its Things id.' This distinguishes it from sibling list-based tools like list_todos, get_today, and search_todos, since it targets exactly one item based on an identifier.

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 strongly implies one should use this tool when a specific to-do ID is already known, and there is nothing about fetching collections. However, it does not explicitly state when not to use it or mention alternative tools such as list_todos or search_todos, so the usage guidance remains implied rather than explicit.

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?

With no annotations provided, the description carries the behavioral disclosure burden. It does reveal that this is a list/read operation and specifies output contents, but it omits explicit reassurance about being read-only and does not mention response behavior like ordering, limits, or potential errors. This is adequate but not deeply 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?

The entire description is one short, front-loaded sentence. Every word contributes meaning: 'List', 'all', 'Things 3 areas', and the output format. There is zero redundancy or 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?

Given that the tool has no parameters and an output schema, the description is contextually complete. It states the single behavior, scope, and expected return contents. Nothing needed to invoke the tool 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain input semantics and it productively indicates what the output includes, id and name, which compensates for any lack of parameter 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?

The description uses a specific verb ('List') and names the exact resource ('all Things 3 areas'), which clearly differentiates it from siblings like list_projects, list_tags, and list_todos. Adding the output fields (id + name) further removes ambiguity.

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 clearly states that this tool retrieves all areas, so an agent can infer it is the right choice when area-level data is needed. It gives clear context but does not explicitly mention when not to use it or name alternatives, though the resource distinction is obvious among the sibling tools.

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?

With no annotations, the description must stand alone. It discloses that the tool returns project fields and that the area parameter filters results, but it does not clarify whether `area` matches by name or ID, or surface edge cases such as empty results or matching behavior. The list nature implies a read operation but that is not explicit.

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

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

The description is deliberately concise: two sentences with the primary purpose and the conditional behavior. No filler, and the key information is front-loaded.

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

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

For a tool with one optional parameter and an output schema, the description is mostly complete. The main missing piece is the precise semantics of the `area` parameter, but the overall tool usage remains clear and the output schema likely handles return-value documentation.

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%, so the description carries the burden. It does add meaning: providing `area` restricts results to projects within that area. However, it does not explain the expected format or source of the area value, leaving some ambiguity for the agent.

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 uses a specific verb and resource: 'List Things 3 projects' and enumerates the returned fields. This clearly distinguishes it from sibling tools like list_todos and list_areas, even without naming them 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 establishes clear context: it lists projects and optionally filters by area. It does not explicitly name alternatives or say when not to use it, but the resource type and behavior make the intended use obvious 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?

With no annotations provided, the description carries the burden of disclosing behavior. The verb 'list' suggests a non-mutating read operation, but the description does not explicitly state read-only semantics, empty-result behavior, or any operational caveats.

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

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

The description is a single sentence that contains the action, the resource, and the scope with no filler or redundancy. It is appropriately front-loaded and easy to parse.

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 zero-parameter list operation, the description is nearly complete. An output schema exists, so return-shape details are not the description's responsibility, and the remaining gap is limited to explicit usage guidance or behavioral caveats.

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

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

The tool has zero parameters and an empty input schema, so there are no parameter semantics for the description to add. The baseline for a zero-parameter tool is 4, and the description correctly focuses on the result rather than parameters.

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 identifies a specific verb ('list') and a concrete resource ('all tag names defined in Things 3'), and clearly distinguishes it from siblings like list_todos, list_areas, and list_projects. The scope is explicit.

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

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

Usage is implied rather than explicitly stated: call this when you need the complete set of tag names. However, the description does not state when to prefer this tool over alternatives or include any exclusions.

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 bares the full responsibility for disclosing behavior. It only says 'list within one scope' and does not explain that it is read-only, that the default filter is 'open', whether results are ordered, or how severe the payload concerns are. This lack of behavioral disclosure can surprise an agent expecting all to-dos regardless of status.

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

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

The description is an eight-word sentence that is front-loaded with the verb and resource. It contains no filler or repetition; given that the detailed parameter schema complements it, the not length is appropriate and every word is meaningful.

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 an output schema present, the description does not need to explain return shape, and the parameter schema covers field specifics. However, the description is very thin: it does not tell the agent when to pick this over search_todos, does not mention default status behavior, and leaves the read-only nature and notable payload risks (which are only described at the parameter level) hidden from the synopsis.

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 each of the 6 parameters having a clear description and (for the fields) a default value. The tool description adds nothing to the parameter semantics, but the rich schema already carries enough weight for this dimension.

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 clearly states a specific verb ('List') and resource ('Things 3 to-dos') with a scope constraint ('within one scope'), so it is far from a tautology. It communicates what the tool returns, though it does not explicitly distinguish it from sibling tools like get_today or search_todos.

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 'within one scope' implies that this tool is best when targeting a particular list/area/project, and the include_notes parameter description products to get_todo() for fetching notes. However, the tool description itself gives no explicit when-to-use guidance or cautions about when to prefer search_todos or other siblings, so the main guidance 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?

There are no annotations, so the description carries the transparency burden. It discloses case-insensitive matching, the default open-only behavior, and how to include completed entries. It doesn't describe output ordering or potential edge cases, but for a read-only search operation these are minor gaps.

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 sentence, no filler. The first sentence states the core operation, and the second explains the important default behavior and how to alter it. The description is front-loaded and each word contributes.

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 search tool with a single required parameter, known defaults, and an output schema, this description is largely complete. Its main omission is explicit guidance about when to use a sibling tool instead, such as when a list without name matching is needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explicitly stating that matching is case-insensitive and by framing include_completed's behavior in the search flow. This goes beyond the individual parameter descriptions.

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?

Description explicitly states 'Search to-dos whose name contains `query`' with a specific verb, resource, and matching rule, plus case-insensitivity. It also conveys the default open-only scope and the optional completed search, making the tool's purpose clear and distinct from siblings like list_todos or get_completed.

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 provides clear context: by default only open to-dos are searched, and include_completed=True switches to also search the Logbook. It gives a meaningful condition for how to broaden a search, though it does not explicitly contrast with sibling tools or state when not to use it.

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?

With no annotations, the description carries the full disclosure burden. It communicates the important first-match-only and OPEN-only behavior, but it does not mention the destructive effects such as replacing tags or removing deadlines, nor what happens when no task matches or when neither todo_id nor query is provided.

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

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

The description is a single front-loaded sentence with no filler. It places the most important behavior first: update, match kind, and state.

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

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

The description plus schema covers most invocation details, but the top-level guidance leaves a notable gap for a 7-parameter tool: it does not state that either todo_id or query must logically be supplied, nor does it explain the update behavior when no match is found or when multiple tasks match. The first-matching behavior partially helps, but edge-case expectations remain implicit.

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?

All 7 parameters have rich schema descriptions that explain matching, tags replacement, deadline removal, and rescheduling. The top-level description adds only the high-level clue that lookup is by todo_id or query, so the schema already does the heavy lifting.

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 clearly states the action ('update') and the resource ('first matching OPEN to-do'), and identifies how the task is found (by todo_id or name query). It does not explicitly name sibling tools like complete_todo or cancel_todo to distinguish from them, so it stops 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?

The description implies when to use it: update an existing open to-do rather than a completed one. It does not explicitly explain when to choose this over complete_todo, cancel_todo, or add_tags, although the schema's tags parameter does mention add_tags for the append case.

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