cortexpad

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

With no annotations, the description discloses key behaviors: 'Purely additive: does not overwrite or clobber content', failure conditions ('fails if `anchor` doesn't match any line'), cap ('Capped to the most recent 20 entries'), and precedence ('`anchor` is ignored when `appendTo` is set').

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 detailed but well-structured, opening with purpose, then explaining modes, failure cases, and alternatives. Slightly long, but every sentence adds information relevant to correct invocation.

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?

Covers all major aspects: purpose, modes, failure, cap, section usage, and relation to alternatives. No output schema, but the tool's return is not central. Completeness is strong for a 6-param 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 already covers all parameters (100%), and the description adds contextual meaning: explains how `anchor` and `appendTo` interact, how `section` groups entries, and backdating behavior for `at`. This exceeds the baseline of 3.

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 'Add a short, dated changelog entry to a note' with scope ('separate from and never touching the note body by default'), and explicitly distinguishes from siblings like update_note/append_to_note via 'Use this instead of...'.

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?

Provides explicit guidance: 'Use this instead of update_note/append_to_note when recording a decision or change without altering the visible note text.' Also details two usage modes (new entry with anchor, appendTo existing) and when each applies, plus mutual exclusivity and failure conditions.

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 full behavioral burden. It discloses the unchecked state and the exact markdown format, which is useful. However, it does not mention where the item is placed in the note, whether the note must exist, or any side effects, leaving some behavioral ambiguity.

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, immediately states the action and output format, and contains no unnecessary words. It is perfectly concise and well-structured.

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 tool with two parameters fully described in the schema and no output schema, the description is largely complete. It explains the core function and format. Minor omissions like append position or error behavior are not critical given the tool's simplicity, so it earns a 4 rather than a 5.

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 already describes both parameters with 100% coverage, so the baseline is 3. The description adds meaning by explaining that the 'item' parameter becomes the text after the '- [ ]' prefix, clarifying the resulting checklist line and providing context beyond the schema's simple 'Item text' label.

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 ('Add'), the resource ('checklist item'), and provides the exact line format ('- [ ] text'). It distinguishes from sibling tools like check_item and uncheck_item, which modify existing items rather than adding new ones.

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

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

The description implies usage (when you want to add a checklist item) but does not explicitly state when to use this tool over alternatives or mention exclusions. No sibling tool is referenced as an alternative for checking/unchecking existing items, so guidance is not fully 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 full burden of behavioral disclosure. It does disclose the idempotent no-op behavior, which is important, but omits other behavioral traits such as error handling (e.g., note not found) and whether the operation requires any permissions. The mutation aspect is implied by 'Add' but not elaborated.

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 that states the core purpose and the most critical behavioral nuance (no-op) without any redundant or tangential information. It is appropriately concise for a simple tool.

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 tool with no output schema, the description covers the primary action and a key behavioral trait (idempotency). It does not explain return values or error cases, but given the simplicity and the clear idempotency note, it is reasonably complete. A 5 would require even more detail, which is not necessary here.

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

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

The schema describes 'id' as 'Note ID' but leaves 'label' with no description, and schema coverage is only 50%. The description does not explicitly explain the parameters; it only implies that 'id' refers to the note and 'label' is the label to add, providing minimal additional meaning beyond the schema. The label's format or constraints are left entirely unspecified.

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 ('Add') and resource ('a label to a note'), which precisely matches the tool name and differentiates it from the sibling 'remove_label'. The parenthetical 'no-op if already present' additionally specifies the exact scope of the operation, making the purpose unambiguous.

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

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

The description implies usage context (adding labels to notes) and the no-op clarification gives a clear behavioral guideline (safe to call multiple times). However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.

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 burden of behavioral disclosure. 'Append text to an existing note' is a mutation, but it does not explain potential failure modes (e.g., nonexistent note), whether appending replaces or adds to the end, or any side effects. This is a significant gap for a mutating tool.

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 with no superfluous words. It is appropriately sized for the tool's simplicity and front-loads the primary action.

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 is too minimal for a tool with no output schema, no annotations, and sibling tools like update_note. It lacks information about return values, error handling, or behavioral nuances, making it insufficient for reliable tool selection in all contexts.

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 50%; the content parameter has a detailed description with formatting rules, but the id parameter is only typed as string with no description. The tool description itself adds no parameter context, leaving id semantics unclear. The rich content description partially compensates.

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 'Append text to an existing note' clearly states the action (append) and the resource (existing note), distinguishing it from create or delete. However, it does not explicitly differentiate from update_note or mention how append differs from replace, so it lacks explicit 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?

No guidance is provided on when to use this tool versus alternatives like update_note. The description simply states the action with no context about prerequisites, typical use cases, or 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly states the error condition when no item matches, describes the matching nuances, and reveals the side effect of triggering the 'all done' push notification on the last item. This exceeds what structured data would provide.

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: it states the action first, then the failure mode and prerequisite, and finally an alternative and a distinctive side effect. Every sentence contributes useful information without repetition or fluff.

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 tool's simplicity (2 params, no output schema, no annotations), the description covers the essential aspects: action, matching behavior, error handling, usage alternatives, and a notable side effect. It does not explicitly describe the return value, but this is a minor gap for a mutation tool where the outcome is clear.

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 already documents both parameters with descriptions (id='Note ID', item includes matching rules). The description reiterates the matching semantics but adds little new parameter-level meaning beyond what the schema already gives, so a baseline score of 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?

The description clearly states the tool's function with a specific verb and resource ('Check off a checklist item in a note') and adds precise matching criteria (case-insensitive, whole-item match, not substring). It distinguishes itself from related tools like update_note and uncheck_item.

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 explicit usage guidance: 'Prefer this over update_note for checking a single item' names a clear alternative and the recommendation. It also instructs to 'call get_note first if you're not sure of the exact wording', providing a prerequisite for correct use.

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 must disclose behavioral details. It only states ownership and the action itself, omitting what happens on success, whether it requires existing resources, or any side effects. It does not mention authentication requirements or return values.

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 is immediately actionable and free of fluff. It earns its place by stating the core function without redundant details.

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

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

For a 3-parameter tool with no annotations and no output schema, the description is underspecified. It lacks guidance on prerequisites, return behavior, or edge cases like the timezone handling mentioned in the schema. The schema partially compensates but the description does not.

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 already describes content and reminderAt in detail, but the description adds nothing about the title parameter or how parameters relate to the note. Title remains undocumented, and the description does not compensate for the 67% 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 the specific verb 'Create' with the resource 'note' and clarifies ownership scope ('owned by the current user'), which clearly distinguishes it from sibling tools like update_note or append_to_note.

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 use for creating a new note but does not explicitly mention when not to use it or direct users to alternatives. There is no reference to append_to_note or update_note for existing notes.

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 full burden of behavioral disclosure. It explicitly states the operation is destructive, permanent, and not reversible via the API, and adds the important instruction to confirm with the user. This is comprehensive for a delete tool with a single ID parameter.

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 only two sentences, front-loaded with the core action and immediately followed by a critical usage warning. Every word earns its place with 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?

Given the simplicity of the tool (one parameter, no output schema), the description covers the essential context: permanent deletion, irreversibility, and confirmation requirement. It lacks details on edge cases like non-existent IDs, but this is not critical for a straightforward delete operation.

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 0% coverage, so the description must compensate. It adds 'by ID' but does not elaborate on what ID format to expect or how to obtain it. For a single parameter, this is minimal but acceptable; the tool name and context make it clear that 'id' refers to a note ID.

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 ('Permanently delete a note by ID'), specifying the verb (delete), resource (note), and scope (by ID). It is unambiguous and distinguishes itself from sibling tools that perform other note operations.

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 on when to use the tool: only after user confirmation, unless the user explicitly asked for deletion. It does not explicitly mention alternatives, but the caution about irreversible deletion serves as implicit guidance, ensuring the agent does not call it prematurely.

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 full burden. It discloses key behavioral details: only open/unchecked items are returned, only unarchived notes are included, and each result carries note ID and title. It does not state whether the operation is read-only or if there are side effects, but the verb 'Get' and the suggestion to check off items afterwards imply a safe read. This is more transparent than many tool descriptions.

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 sentences. The first sentence states exactly what the tool returns, and the second sentence provides actionable guidance. There is no wasted verbiage, and the 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?

The description is complete for a simple read-only tool. It covers the scope (open items, unarchived notes), the output (note ID and title), and usage context (start of session). Even without an output schema, the user understands what to expect. It also provides a helpful cross-reference to check_item, making it 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?

The tool has zero parameters, and the schema is empty (100% coverage). The description adds no parameter-specific details, but none are needed. Per the baseline for zero-parameter tools, this 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 description clearly states the tool's function: retrieving the user's open (unchecked) checklist items across all unarchived notes. It specifies the output includes note ID and title, distinguishing it from sibling tools like list_notes or check_item. The verb 'Get' is specific and matches the tool name.

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 explicitly instructs when to use the tool: 'Call this at the start of a session to pick up tasks the user left for you.' It also provides follow-up guidance on how to act on results, including using check_item to complete tasks. This is clear, actionable usage direction.

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 burden. It discloses that only notes owned by the current user are returned and that invalid or unauthorized IDs fail. This is valuable context, though it doesn't detail error types or any limitations beyond ownership. For a simple getter, this is sufficient.

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 three concise sentences. The first front-loads the core purpose, the second clarifies ownership and failure, and the third gives actionable guidance. Every sentence earns its place with no redundancy.

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

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

For a simple one-parameter retrieval tool with no output schema or annotations, the description covers purpose, access restrictions, failure behavior, and a specific use case. The hint about checklist items implies the return content is comprehensive enough for such operations, making the description complete for an agent.

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 only defines 'id' as a string. The description adds meaning by stating that the ID must belong to the current user and that other IDs cause failure, clarifying the parameter's valid domain. It does not further specify format, but the added semantics are useful given 0% schema description 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 clearly states the tool's function: 'Get a single note by ID, full content included.' It uses a specific verb and resource, and the phrase 'single note' distinguishes it from list_notes and other sibling tools that operate on multiple items.

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

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

Explicitly recommends using this tool 'before check_item/uncheck_item when you're not sure of a checklist item's exact text,' providing a concrete use case. However, it does not name alternatives for listing multiple notes or exclude other scenarios, so it lacks a comprehensive when-not/alternatives comparison.

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. It discloses that the timezone may not be set ('if set') and explains the purpose of the setting, which aids the agent in interpreting results. However, it does not specify the full structure of settings or whether other settings are included, leaving minor uncertainty about the return payload.

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 concise sentences, each earning its place. The first sentence states the tool's purpose and key data point. The second provides a specific usage rule with an example. No wasted words, and the most critical 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 no-parameter getter with no output schema, the description provides sufficient context: what it returns, that the timezone is optional, and when to use it. The example ('Europe/Berlin') clarifies the expected format. The use case for converting local times is fully explained, making the tool self-contained in context.

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 the schema is empty, so there is nothing to document. The description adds context about the timezone value, which is more about the return data than parameters. With no parameters, the baseline of 4 is appropriate; description does not need to compensate for missing parameter info.

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 tool retrieves the user's stored settings, with a specific emphasis on the IANA timezone. It distinguishes itself from siblings by focusing on settings retrieval, which no other sibling covers. The verb 'get' and resource 'settings' are specific and unambiguous.

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

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

Explicitly says to use this tool to convert spoken local times into UTC reminderAt, and instructs to never guess or assume the user's timezone. This provides clear when-to-use guidance and implicitly warns against alternatives (assuming timezone). The instruction is actionable and directly tied to a common use case.

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 conveys key behaviors: it returns only the current user's notes, performs case-insensitive substring matching on title/content, defaults to unarchived notes, and orders by newest/pinned first. It does not mention pagination or response shape, but for a read-only list tool this is solid transparency.

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, front-loaded with the verb and resource, then compressed search semantics and a clear usage directive. Every sentence earns its place without 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?

Without an output schema or annotations, the description covers purpose, behavior, and usage context well. It could clarify what fields are returned (e.g., full objects vs. just IDs), but it explicitly frames the tool as an ID-finder, which is sufficient for its intended workflow.

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. The description adds meaning beyond the schema: it explains that 'query' matches title or content case-insensitively and that the default is unarchived notes, which clarifies the 'archived' parameter's default behavior. This enriches parameter understanding.

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 'List or search the current user's notes only,' clearly specifying the verb, resource, and scope. It also distinguishes itself from siblings by stating its use case: finding a note ID before calling get_note, update_note, or checklist/label 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 explicitly says 'Use this to find a note's ID before calling get_note, update_note, or the checklist/label tools, which all require one.' This provides clear when-to-use guidance and names the alternatives, satisfying the highest bar for usage guidelines.

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 fully discloses the irreversible destructive nature, the side effect of stripping the '((n))' marker, and the decrementing of the lifetime section counter. It also explains the failure mode when multiple entries share n, which is critical behavior beyond 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?

The description is front-loaded with the purpose and proceeds logically through side effects, caveats, and remediation. Every sentence adds necessary detail for a tool with nuanced behavior, making it appropriately sized and well structured.

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 tool's destructive nature, lack of annotations, and absence of an output schema, the description comprehensively covers its behavior: side effects, failure mode, and a suggested pre-step. It fully satisfies the need for contextual completeness.

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 already covers all parameters with descriptions, but the description adds essential nuance by explaining that n is not a unique ID and that `at` differentiates entries sharing the same n. This enriches parameter understanding beyond the schema's baseline.

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 'Permanently remove a single changelog entry' which clearly states the verb, resource, and scope. It distinguishes from siblings like add_changelog_entry and delete_note by specifying it targets a single entry within a note, not the note itself.

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 concrete usage guidance including when to pass `at` for disambiguation and recommends calling `get_note` first if unsure about shared marker numbers. It does not explicitly mention alternatives for other scenarios, but the get_note reference and the handling of ambiguous cases serve as effective direction.

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 full burden of behavioral disclosure. It only states the bare operation without explaining side effects, error handling, idempotency, or permissions, leaving the tool's behavior largely opaque.

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 short sentence that communicates the essential action without any wasted words. It is perfectly concise and 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 mutation tool with no annotations and no output schema, the description is too sparse. It does not address what happens if the label or note doesn't exist, whether prior conditions are required, or what the result is, making it incomplete for reliable agent use.

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 50% coverage (only 'id' is described). The description does not add any meaning to the 'label' parameter beyond its name, nor does it clarify constraints or formatting. It fails to compensate for the missing schema 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 clearly states the specific action ('Remove a label') on a specific resource ('a note'), distinguishing it from sibling tools like add_label. It is unambiguous and uses a strong verb+resource structure.

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 does not explicitly state when to use this tool versus alternatives such as add_label. The intended usage is implied by the tool name and description, but there is no guidance on exclusions, alternatives, or edge cases.

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 transparency burden. It discloses matching semantics, error on no match, and a prerequisite. However, it does not specify behavior for multiple matches or idempotency when the item is already unchecked.

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, front-loaded with the action, and no wasted words. Every phrase adds meaning.

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 2-parameter tool with no output schema, the description covers the action, matching behavior, error case, and a fallback. Minor gaps about multiple matches and return value keep it from a 5.

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% for both parameters, and the description repeats the item-matching details already in the schema. No additional parameter insight is provided beyond the schema, so 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?

The description clearly states the verb 'Uncheck' and the resource 'a checklist item in a note', with explicit matching rules (case-insensitive, whole-item match). This fully differentiates it from siblings like check_item or add_checklist_item.

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 concrete guidance by advising to call get_note first if unsure of exact wording, and notes the error condition. It does not explicitly contrast with check_item, but the usage context is clear enough.

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 explaining behavior. It discloses partial update semantics (only passed fields change) and labels as a full replace, which is critical for safe use. It does not mention error handling or permissions, but these are not essential for basic operation.

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 concise, front-loaded with the core action, and uses two clear sentences. Every phrase carries meaning, 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?

Given the tool's complexity (8 params, no output schema), the description relies on rich schema descriptions for details. It covers update semantics and content vs append, but could add a note about required 'id' (already in schema) or behavior when the note doesn't exist. Overall, it is sufficient for an agent to use the tool correctly.

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

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

Schema descriptions already cover 75% of parameters, so the baseline is 3. The description adds extra value by explaining the overall partial-update behavior and explicitly contrasting 'content' with append_to_note, going beyond the schema's per-field 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 clearly states the action ('Update an existing note') with a specific verb and resource. It also distinguishes from the sibling tool 'append_to_note' by contrasting full content overwrite with appending, making its purpose unambiguous.

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

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

The description explicitly directs users to 'append_to_note' when only adding text, and the schema description for labels recommends 'add_label/remove_label' for single-label changes. This provides solid alternatives, though the main description could have explicitly mentioned all sibling distinctions.

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