hjarni

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description consistently describes a non-destructive creation operation. It adds valuable context beyond annotations, such as the behavior of nesting via parent_id, team-specific scoping, and a follow-up suggestion (instructions-update). No contradictions with annotations.

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

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

The description is a single paragraph of about 5 sentences, front-loaded with the main purpose. It is reasonably concise, though the follow-up suggestion and some parameter details could be slightly tighter. Every sentence adds value.

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

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

Given 5 parameters (all described in schema) and the additional description, the tool is fairly complete. However, there is no output schema and the description does not mention what the tool returns (e.g., the created container object), which would help an agent understand the response. A mention of return value or response structure would improve 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?

Schema description coverage is 100%, but the description adds meaning beyond it: it clarifies the concept of negative_space, explains that parent_id can be null/omitted for top-level, and notes that parent_id must belong to the same team when team_id is set. This adds value over the schema's brief 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 tool's purpose: 'Create a new container (folder) for organizing notes.' It uses a specific verb ('create') and resource ('container'), and the function is distinct from siblings like containers-get, containers-list, and containers-update.

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 explains when to use this tool (to create a container) and describes key parameters and constraints (e.g., parent_id must belong to same team as team_id). However, it does not explicitly state when not to use it or provide direct comparisons to sibling tools, though context makes this mostly clear.

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 provide readOnlyHint=true and idempotentHint=true, and the description adds useful behavioral details like returning notes_count, children_count, negative_space, and LLM instructions, plus the optional include_tree parameter. No contradictions.

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, well-structured sentence with a clear list of returned fields. It is concise and front-loaded with the core purpose. No unnecessary words.

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?

Despite no output schema, the description fully enumerates the fields returned, including the optional tree structure. For a simple get-by-ID tool, this is complete and 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?

Schema coverage is 100%, and the description adds context beyond the schema: it specifies id is required and explains include_tree as 'ancestor chain and children'. This adds value but is not exhaustive.

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 'Get a single container by ID', specifying the verb and resource. It lists the fields returned and distinguishes from sibling tools like containers-list which would return multiple containers.

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 indicates when to use (get a single container by ID). It lacks explicit when-not-to-use guidance, such as suggesting containers-list for multiple containers, but the purpose is sufficiently clear.

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 indicate readOnlyHint and idempotentHint, so the tool is safe. The description adds context about shared containers being automatically included and scope restrictions for 'archived'. It could mention pagination limits or ordering 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 three sentences: purpose, returned fields, and parameter notes. It is front-loaded with the core action and efficiently adds necessary details 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?

The description covers purpose and parameters adequately for a read-only list tool with no output schema. However, it lacks details on pagination behavior (default page size, ordering) and does not describe the full response structure beyond notes_count and children_count.

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

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

Schema coverage is 100% and already describes all parameters. The description adds value by clarifying the default scope value and the restriction that 'archived' only applies to personal containers, which is not clear from the schema alone.

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 (List) and resource (containers/folders) for organizing notes. It distinguishes this from sibling tools like containers-get (single) and containers-create by its listing purpose.

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 explains optional parameters (team_id, scope, page, per_page) and a special case for shared containers. However, it does not provide explicit guidance on when to prefer this over alternatives (e.g., containers-get for a single container) or 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?

Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds crucial behavioral details: roles cascade to descendants, 'inherit' clears explicit role, team owners cannot be downgraded. It also states the return value (effective_role). This fully informs the agent about side effects and constraints.

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 yet comprehensive, with every sentence adding value. It is front-loaded with the main action and then adds details about behavior, requirements, and return value. No superfluous text.

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

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

For a tool that manages permissions with inheritance and specific constraints, the description covers all necessary context: cascading behavior, the meaning of 'inherit', required roles for the caller, and what is returned. No output schema exists, but the description fills that gap by stating the return value (effective_role).

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% with clear parameter descriptions, but the tool description adds extra context: explains that 'inherit' is used to delete an explicit role, that container_id must be a team container, and user_id must be a team member. This goes beyond the schema definitions.

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: 'Set or clear a team member's role on a team container.' It specifies the verb (set/clear), resource (role on container), and distinguishes from sibling tools like containers-create or containers-get. Very clear purpose.

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 explains when to use this tool (to set or clear a role), provides context about behavior (cascading roles), and lists prerequisites (caller must have admin role, container must be team container, user must be a member of the same team). It does not explicitly name alternatives but implies that for other container operations, use other 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?

Annotations provide readOnlyHint=false, destructiveHint=true, idempotentHint=true. The description adds behavioral context: the role requirement for team containers and that negative_space can be cleared by passing null. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, then provides scope and a concise parameter list. No unnecessary words or sentences.

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 tool's actions, parameter behaviors, and access requirements. It lacks explicit error conditions or response format, but with no output schema, the response is not expected. Annotations supplement 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?

Schema description coverage is 100%, so the schema already documents each parameter. The description rephrases some parameters (e.g., 'pass null to clear it' for negative_space) but adds minimal new semantic meaning beyond synthesis and context.

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 starts with 'Update an existing container' and enumerates specific actions: rename, change description, negative_space, move parent, set position. This clearly distinguishes it from sibling tools like containers-get (read), containers-create (create), and containers-permissions (permissions).

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 specifies that the tool works for both personal and team containers the user can edit, and that team containers require the editor role. It implies usage for updating existing containers, not for creating or reading, but lacks explicit exclusions or alternative tool suggestions.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds context about the ordering of recent_changes (newest edit first) and the conditional behavior when the dashboard is empty, going beyond annotations to disclose important behavioral traits.

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 every sentence adds value. It could be slightly more concise, but it is front-loaded with the core purpose and well-structured. Minor deduction for length.

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 no output schema and zero parameters, the description sufficiently explains the return fields (counts, recent_notes, recent_changes) and the conditional behavior. It provides complete context for an agent to use the tool appropriately.

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?

No parameters required, and schema coverage is 100%. The description emphasizes 'No parameters required,' which is sufficient. Baseline is 4 for zero-parameter tools.

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 returns a dashboard overview with counts of notes, containers, tags, inbox items, plus recent_notes and recent_changes. It is specific about what is returned and distinguishes itself from sibling tools (no other dashboard tool).

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 states when to use recent_changes ('to orient at the start of a conversation') and provides a conditional: if empty, call 'me' and follow onboarding. This gives clear guidance on when to use this tool vs alternatives.

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 provide no idempotent or destructive hints, so description carries burden. Description clarifies it's for system feedback, but doesn't mention side effects or storage. Additive but could state feedback is stored and reviewed.

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?

Description is thorough but slightly long. Front-loads purpose, then details parameters. No wasted sentences, but could be more concise by combining some sentences.

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

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

No output schema, so description must explain what feedback submission entails. Covers all parameters and provides usage guidance. Minor gap: doesn't describe post-submission behavior (e.g., confirmation, storage).

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%, description adds significant value: explains category enum, gives defaults (severity default medium), clarifies context as JSON-encoded string with examples. Exceeds 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?

Description clearly states 'Submit feedback about Hjarni itself' with specific examples (confusing tool descriptions, missing capabilities). Explicitly distinguishes from sibling tool notes-create by stating what NOT to use it for.

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 when to use (for issues with MCP server, tools, product behavior) and when not to (user's own notes belong in notes-create). Provides alternative tool name.

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 are minimal (readOnlyHint=false, destructiveHint=false). Description adds token-saving advice for large files but does not mention other behavioral traits like file size limits, permissions required, or whether the note must exist. Lacks full transparency expected for a write 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 (3 sentences) and front-loaded with the core action. Every sentence adds value: purpose, usage guidelines, and parameter summary. 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?

Given the tool has 5 parameters, no output schema, and basic annotations, the description covers the essential context: which tool to use, required/optional params, and default MIME type. It could mention file size limits or note existence, but is mostly complete for a simple attachment tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description summarizes them and adds default for content_type, but does not add significant new meaning beyond what the schema provides. Baseline 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 action (attach a file), the resource (personal notes), and the method (via base64-encoded data). It also distinguishes from the sibling tool files-create_upload_url by specifying scope (personal vs team/shared) and efficiency (large files).

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 states when to use this tool ('personal notes only') and when not to (use files-create_upload_url for team/shared notes or large files to save tokens). Provides clear alternatives.

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 show read/write, non-destructive, non-idempotent. Description adds that tool follows one redirect and defaults for filename and content_type. Could mention error handling or overwrite behavior, but overall good context beyond annotations.

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

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

Two sentences, no fluff. First sentence states purpose and scope, second lists parameters. Efficient 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 simple attach-from-URL tool with no output schema and 5 parameters fully described, the description covers all necessary context: purpose, scope, parameters, and redirect behavior.

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 baseline 3. Description enumerates each parameter with required/optional status and default behaviors, providing value beyond 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?

Explicitly states 'Fetch a file from a public URL and attach it to one of your personal notes', with specific verb+resource. Distinguishes from sibling 'files-create_upload_url' for team/shared notes.

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 when-to-use (personal notes only) and when-not-to-use (team/shared notes), naming the alternative tool. Also notes redirect behavior and required vs optional parameters.

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?

Describes all three possible return statuses ('pending', 'completed', 'expired') and their meanings beyond annotations. Annotations already indicate readOnlyHint and idempotentHint, and the description adds valuable behavioral details like timeout expiration and metadata inclusion.

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 efficiently covering purpose, required parameter, and possible outcomes. No redundant information; all text adds value.

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

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

For a simple check tool with one parameter and no output schema, the description fully explains inputs, outcomes, and behavior. Annotations cover safety. No 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 has 100% coverage with description for token. The tool description adds context about token origin (from files-create_upload_url response), making the parameter semantics clearer than schema alone.

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?

Explicitly states 'Check the status of a file upload created by files-create_upload_url' with specific verb and resource. Distinguishes from sibling tools like files-create_upload_url and files-attach by clearly stating its role as a status check.

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?

States required parameter token and its source from files-create_upload_url response. Implicitly connects to the upload-creation workflow. Could be more explicit about when not to use, but context is clear given 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?

Beyond annotations, the description adds behavioral details: one-time URL, 30-minute expiration, token savings, and required note_id. No contradictions with annotations.

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

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

Four sentences, each adding value: purpose, token savings, expiration, follow-up, and parameter requirements. No wasted words.

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 2 parameters and no output schema, the description provides sufficient context (expiration, follow-up) for an AI agent to use 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 coverage is 100%, so the schema already describes both parameters. The description merely restates required/optional, adding no new semantics beyond that.

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 it generates a one-time upload URL for attaching a file to a note, with specifics on token savings and expiration. It distinguishes itself from siblings like files-attach and files-check_upload.

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 tells when to use (to attach files with token savings) and mentions the follow-up tool (files-check_upload). However, it does not explicitly state when not to use or compare with alternatives.

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 indicate readOnlyHint, idempotentHint, destructiveHint. The description adds transparency about the URL being temporary and expiring 'after a few minutes', which is not covered by annotations.

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

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

Three sentences with no wasted words. The first sentence states the purpose, the second provides usage guidance, and the third lists required parameters and key behavioral detail (expiration).

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 tool lacks an output schema, but the description fully covers the return value (a temporary download URL) and its lifetime. Required parameters are explicitly listed, making the description complete for a simple retrieval 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 coverage is 100% for both parameters. The description adds semantic value by specifying that file_id should come from 'notes-get response', which helps the agent select the correct value.

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 'get' and the resource 'temporary download URL for a file attached to a note'. It distinguishes this tool from sibling file tools like files-attach and files-remove by focusing on URL retrieval.

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 advises to 'Share the URL with the user to download in their browser' and notes the URL expiration. While it doesn't explicitly state when to not use this tool, the action is singular and no alternative exists among siblings, so guidance is sufficient.

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 provide destructiveHint=true; description adds 'irreversible' and 'personal notes only', but does not detail error behavior or effects on other data.

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 main action, no unnecessary words. Efficiently conveys core 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?

For a simple destructive tool with two parameters and no output schema, the description covers essentials. Lacks error handling details but sufficient for basic invocation.

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

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

Schema coverage is 100% and description repeats parameter info, adding minimal extra context beyond the schema's own 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 specifies the action (permanently remove a file attachment) and the resource (personal notes only), distinguishing it from sibling tools like files-attach or files-get_download_url.

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 states required parameters and that file_id comes from notes-get response, but does not explicitly mention when not to use the tool or alternative 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?

Annotations already indicate readOnly, idempotent, non-destructive. Description adds context about defaulting behavior, inheritance chain for container level, and response fields (resolved_level, defaulted_level), going beyond annotation info.

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?

Four sentences covering purpose, usage, and parameter details. Well-structured and informative, though slightly verbose in explaining default behavior. No unnecessary words.

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

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

No output schema, but description explains return structure (resolved_level, defaulted_level, inheritance chain). Covers all parameter functions and usage contexts. Adequately complete for a getter tool with strong annotations.

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 covers 100% of parameters, baseline 3. Description adds meaning: explains default behavior for level (defaults to brain), and that id is required for container/team, elaborating on schema definitions.

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 clearly states 'Get LLM instructions at the specified level' with specific verb 'Get' and resource 'LLM instructions'. It distinguishes from siblings like instructions-update by focusing on retrieval.

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 calling with level 'brain' early in conversations to learn user preferences. Explains behavior for different levels and parameter requirements, though does not provide explicit when-not-to-use scenarios.

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?

Beyond annotations (destructiveHint=true), description warns about losing content and advises reading existing instructions first. Modes (replace/append) are clearly explained, adding behavioral context.

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

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

Concise single paragraph, front-loaded with main action, each sentence adds distinct value without redundancy 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?

Comprehensive coverage: no output schema, but explanation of behavior (overwrite/append), prerequisites (team ownership), and safety advice makes the description complete for a mutation 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?

Despite 100% schema coverage, description adds semantic value by explaining level meanings, id requirement logic, mode behaviors, and best practices, going beyond raw schema definitions.

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 updates LLM instructions at a specified level, listing all level options and distinguishing from sibling tools like instructions-get.

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 guidelines: required and optional fields, id requirement for container/team levels, mode options with default, and crucial advice to read current instructions first before replacing.

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?

Description aligns with annotations (destructiveHint=true), explicitly stating unlinking is destructive and irreversible. Adds context that it does not modify body text.

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, focused sentences. No redundancy, front-loaded with core 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?

For a simple tool with no output schema, the description fully covers purpose, usage context, parameter requirements, and safety warnings.

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 baseline 3. Description repeats required parameters and enum values but adds minimal new semantic value beyond the schema.

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

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

Clearly states the tool creates or removes bidirectional links between notes. Differentiates from sibling tools like tags-manage by specifying the action on links.

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 advises preferring wiki-link syntax for inline linking and reserves this tool for programmatic links without body modification. Also warns about destructive unlink behavior.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context beyond these: it specifies the precise data returned (onboarding.completed, onboarding.missing_steps, email, plan) and explicitly states what is NOT returned ('never billing or token metadata'). This full disclosure helps the agent understand the tool's 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 concise (4 sentences) but packs significant detail: purpose, usage recommendation, specific data fields, and limitations. It is front-loaded with the primary action, then usage context, then details. 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?

Even without an output schema, the description fully explains what the tool returns (profile, plan, onboarding state with specific fields, email, team memberships, note quota) and explicitly states what it excludes. Given the tool's simplicity (no parameters), this is complete for an agent to use 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?

The input schema has no parameters, and description states 'No parameters required.' With 100% schema coverage (none), the description doesn't need to add parameter semantics. Baseline 4 is appropriate; no additional value needed.

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 'Get the connected user's profile, plan, onboarding state, team memberships, and note quota in a single call.' This specifies the verb (Get), resource (connected user's profile, plan, etc.), and distinguishes it from sibling tools (e.g., notes, containers, teams) which deal with different entities.

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 advises to 'Call this once at the start of a conversation' and explains how the returned data can be used: greet user by first name, run onboarding script when needed, route notes, avoid Pro features for free users. Also notes that no parameters are required. This provides clear guidance on when and how to use the tool.

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?

Discloses that notes start with status 'active' (beyond annotations). Does not contradict annotations (readOnlyHint=false etc.). No mention of auth or rate limits, but annotations lower the bar.

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?

Description is moderately concise and well-structured, front-loading purpose and listing parameters with caveats. Not overly verbose, but could be more scannable (e.g., bullet points).

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 8 parameters and gives usage tips, but lacks details about return value (e.g., note ID). With no output schema, this is a notable gap. Otherwise 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?

Schema coverage is 100%, but description adds value: explains summary is required by convention, tag_list is comma-separated, review_after for time-boxed notes, and provides an example. Exceeds 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 clearly states 'Create a new note' and specifies the required parameter (title). It lists optional parameters and distinguishes from sibling tools like update/delete, but could contrast more explicitly with current and related 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?

Provides some usage guidance (summary required by convention, review_after for time-boxed notes) but does not explicitly state when to use this tool vs alternatives like notes-update or containers-create. Lacks 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?

Annotations declare destructiveHint=true, but the description adds that the deletion is recoverable, specifies the restore mechanism (notes-restore), mentions the purge date (30 days), and indicates that attachments and history are affected. This goes beyond annotations and provides full behavioral context.

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

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

The description is four sentences, front-loaded with the main action and recoverability. Every sentence adds value—scope, constraints, and recovery differentiation—with no wasted words.

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 delete tool with one required param and no output schema, the description covers the action, recoverability, usage scope, and constraints. It fully informs the agent of what the tool does and its side effects.

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% coverage (one parameter 'id' with a description). The description only restates that 'id (integer)' is required, adding no new meaning beyond the schema. According to rules, baseline is 3 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 clearly states the action 'Move a note to Trash' on the specific resource 'note'. It explicitly distinguishes from permanent deletion by noting recoverability, and it differentiates from sibling 'notes-restore' by describing the delete action.

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 explicit guidance on when to use (personal and team notes with editor role) and when not to use (cannot delete notes in a shared container). It also mentions the alternative 'notes-restore' for undoing a delete, giving clear when-to and when-not-to usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description need not repeat these. It adds useful behavioral context by detailing the returned data (e.g., 'inherited LLM instructions'), which goes beyond annotations. There is no contradiction. It could mention what happens if the ID is invalid, but the annotations provide sufficient safety profile.

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

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

The description is a single sentence that directly states the purpose and required input, then lists outputs. It is front-loaded with the core action ('Get a single note by ID'). Every phrase earns its place; there is no wasted text.

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

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

Given the tool is a simple read operation with strong annotations (readOnlyHint, idempotentHint) and no output schema, the description sufficiently covers what is returned. It does not address error cases or pagination (not applicable). It is complete enough for effective use, though a brief note on error behavior would be beneficial.

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 single parameter 'id' has schema description 'Note ID (required)'. The tool description repeats this as 'Required: id (integer).' With 100% schema coverage, the description adds no additional meaning about the parameter format, constraints, or example values. 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 'Get a single note by ID' and enumerates the specific content returned (Markdown body, tags, container path, linked notes, backlinks, file attachments, inherited LLM instructions). This distinguishes it from sibling tools like notes-list (which lists multiple notes) and notes-create/update/delete (which modify notes).

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 states 'Required: id (integer)', which is necessary for usage. It implicitly clarifies that you use this tool when you have a specific note ID. However, it does not explicitly state when not to use it (e.g., for listing multiple notes use notes-list) or provide alternatives, which would improve 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 provide readOnlyHint, idempotentHint, destructiveHint. The description supplements with details on what data is returned (who, when, what changed) and parameter effects like include_body reconstructing full text. No contradictions with annotations.

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

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

A single paragraph front-loaded with purpose, followed by parameter details. Every sentence adds value—no filler. Efficient 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?

No output schema provided, but the description gives a good sense of what is returned (who, when, what changed). Could be slightly more explicit about the structure (e.g., list of revisions). Overall sufficient for a read-only history 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 coverage is 100%, but the description adds significant value: explains default for limit (20), max (100), meaning of before_seq for pagination, what include_body does, and that seq returns only that revision with full body. This goes well beyond the 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 starts with a specific verb and resource: 'Read a note's revision history and provenance.' It clearly distinguishes from siblings like notes-get (current version) and notes-revert (revert). The mention of 'who wrote each version' and 'what changed' adds specificity.

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 states when to use: 'attribute facts to their source' and 'see recent edits before making your own.' Implicitly tells when not by highlighting what it provides (history vs current version). Lacks explicit exclusion of other tools but is clear enough for an AI agent.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds significant behavioral details: pagination, filtering rules (e.g., scope only for personal notes, trashed list behavior with restore reference), and handling of empty results. Exceeds annotation burden.

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?

Well-structured: opens with clear summary, lists options systematically, includes an illustrative example, and ends with actionable fallback. Every sentence is informative 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?

Given the complexity (11 parameters, no output schema), the description is thorough. It covers all filtering options, combinations, defaults, edge cases (empty list, scope restrictions), and references sibling tool for restore. No gaps remain.

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

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

Schema coverage is 100%, and the description adds substantial meaning: explains combinations (team_id + container_id), provides example usage, clarifies stale vs summary_stale, specifies max for per_page and defaults. Goes well beyond 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?

Clearly states 'List notes with optional filtering, sorting, and pagination.' Distinguishes from sibling tools like notes-create, notes-delete, notes-get, etc., by specifying the action and optional parameters.

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 clear context for when to use, including filtering options, sorting, pagination, and an example. Includes fallback instructions when list is empty. However, it does not explicitly compare to sibling tools like 'search' or 'notes-get' for when to choose this instead.

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

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

Description adds details beyond annotations: restores body, tags, attachments, history, and has a time constraint (purge date). Annotations provide idempotentHint and destructiveHint, which are consistent.

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 action and condition, then required parameter. No wasted words.

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 single-parameter tool with no output schema, the description covers purpose, condition, and parameter semantics completely.

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% with one parameter. Description adds context: 'the same note id you deleted', which aids understanding beyond the 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 tool restores a note from Trash, bringing back its body, tags, attachments, and history. It references the sibling 'notes-delete' tool, distinguishing it from other notes 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?

Explicitly states when to use (after notes-delete, before purge date) and implies when not to use. Does not explicitly list alternatives, but the context is clear.

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?

Beyond annotations (destructiveHint=true), the description explains that the operation does not erase history but appends a new revision attributed to the user, and that the revert can itself be undone. It also details the expected_lock_version guard to prevent clobbering.

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 (4 sentences) with front-loaded purpose, followed by behavioral details and parameter guidance. Every sentence adds value 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?

Given no output schema, the description adequately explains the effect (appends new revision, not destructive to history), mentions undoability, and covers the lock version guard. It is complete for a mutation tool with moderate complexity.

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?

While schema covers 100% of parameters, the description adds meaningful context: it reiterates required parameters, explains the purpose of seq (restore body to that revision), and elaborates on expected_lock_version as a concurrent-edit guard, providing value beyond schema.

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

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

The description clearly states the tool reverts a note's body to an earlier revision, specifies it appends a new revision rather than erasing history, and distinguishes from siblings like notes-update and notes-restore by referencing notes-history for finding the seq.

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 states 'Use only when the user explicitly asks to undo a change' and provides prerequisite steps (find seq via notes-history), giving clear context for when and how to use this tool.

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?

Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds critical behavioral context: 'Every edit is recorded as a named, revertable revision attributed to you' and explains that surgical edits are anchor-based and safe without lock_version for body changes but other fields still need protection. There is no contradiction with annotations.

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

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

The description is thorough but lengthy; however, it is well-structured with general actions first, followed by parameter details grouped by category, and ends with concrete examples. Every sentence adds value, and the front-loading of purpose aids quick comprehension. Slightly verbose but justified by complexity.

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 27 parameters, high complexity, and no output schema, the description fully covers all aspects: parameter interactions, concurrency, freshness, organizational fields, and edge cases. Examples cover major use cases. No gaps are apparent.

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%, but the description adds substantial meaning beyond the schema: mutual exclusivity of body-mutation modes, precedence of tag_list over add_tags/remove_tags, anchor matching rules, and the expected_lock_version interaction. Examples clarify complex parameter relationships.

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 'Update a note' with specific actions (edit content, move folder, archive, favorite, change tags). It distinguishes itself from siblings by noting 'This is the tool for moving notes between folders; there is no separate move tool.' The verb-resource pair is precise 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?

The description provides explicit when-to-use guidance, such as 'This is the tool for moving notes between folders; there is no separate move tool.' It explains concurrent edit safety with expected_lock_version and gives examples for each mutation mode. It also references alternative tools (notes-history, notes-revert) for related operations.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: results grouped by type, pagination metadata, snippet inclusion, and a special empty-result handler.

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 well-structured, starting with high-level purpose, then systematically detailing parameters, and ending with a special case. Every sentence adds value, and the most critical info 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?

Without an output schema, the description explains return values (grouped by type with pagination metadata and snippets). However, it does not mention error conditions or edge cases, slightly reducing 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?

Schema coverage is 100%, baseline 3. The description adds substantial context: default types, search_scope options, container_id behavior, include_body details, tag filtering logic, pagination defaults, and datetime format examples.

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

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

The description clearly states 'Search across notes, containers, and tags in one call,' which is a specific verb+resource combination that distinguishes it from siblings like notes-list or containers-list.

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?

While the description does not explicitly contrast with alternatives, it provides guidance on when to use (unified search) and a specific instruction for empty results (call me and run onboarding). It lacks explicit 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?

Annotations provide basic non-readonly status, but description adds valuable context: tag names are auto-lowercased and duplicate checks are recommended. Not disclosed what happens on duplicate (no idempotency).

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 sentences, front-loaded with core action, no redundant words. Efficient and to the point.

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 creation, required parameter, duplicate avoidance, and a behavioral note. No output schema needed; sufficient for agent to invoke 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?

Parameter 'name' is fully described in schema with 'Tag name (required)'. Description adds behavioral detail about lowercasing, which is beyond schema.

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

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

Clearly states 'Create a new tag' with verb and resource. Differentiates from siblings like tags-list and tags-manage by specifying creation action and noting lowercasing behavior.

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 advises to check tags-list first to avoid duplicates, providing context for appropriate use. Lacks explicit alternatives or when-not-to-use, but clear guidance exists.

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?

Adds beyond annotations: specifies paginated and includes notes_count. No contradictions with readOnlyHint and idempotentHint.

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, no fluff, key info 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?

Complete for a list tool; no output schema but mentions notes_count. Could note default pagination values but not necessary.

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%, each parameter described in schema. Description only repeats parameter types, not adding meaning beyond schema.

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

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

Clearly states it lists all tags with notes_count and is paginated. Distinguishes from sibling tools like tags-create and tags-manage.

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?

Implies usage for listing tags, but no explicit when-to-use or alternatives. Adequate for a simple list tool.

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 details each action: rename behavior, merge moves notes and deletes source (creating destination if missing), delete removes tag with no-op on missing. It warns of destructiveness and irreversibility, adding significant value beyond annotations.

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

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

The description is a single dense paragraph that efficiently conveys all necessary information. It could benefit from bullet points or clearer structuring, but every sentence is substantive and front-loaded with the overall purpose.

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 tool has 6 parameters and no output schema; the description thoroughly explains all actions and edge cases (no-op delete, auto-create target). It lacks details about return values or response format, but overall it is comprehensive for a cleanup 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 coverage is 100% with descriptions for each parameter, but the description adds context: case-insensitivity, conditional requirements (new_name for rename, target for merge), and auto-creation of merge target. This enhances usability beyond the schema alone.

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 it renames, merges, or deletes a tag, explicitly contrasting with notes-update which edits tags on notes. It specifies the resource as 'the tag itself' and calls it 'cleanup tools for the tag list', 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 gives clear context for when to use (tag cleanup) and when to avoid (notes-update for editing note tags). It suggests checking tags-list before destructive actions but does not explicitly state scenarios where the tool should not be used.

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?

Beyond annotations, the description discloses that no charge is incurred until an invited teammate accepts, and that users can only have one free team, with an error returned if they already own an unsubscribed team. This adds valuable context not present in annotations.

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

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

The description is concise (about 100 words) and front-loaded with the main purpose. Each sentence adds value without fluff. Slight improvement could be grouping related info, but overall efficient.

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 and the annotations, the description covers purpose, ownership, ref usage, billing, error handling, and next steps. No gaps remain for an agent to use this 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 description coverage is 100%, so the description adds limited new meaning. For `ref`, it reinforces the schema's guidance. For `name`, no additional info. 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 'Create a new team owned by the user (they become the owner)', specifying verb, resource, and ownership. This distinguishes it from sibling tools like teams-invite, teams-get, and teams-list, which have different purposes.

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 on the `ref` parameter: only use 'assistant_suggestion' when responding to me.suggestions.create_team, otherwise omit. Also advises to use teams-invite after creation and to handle the error about upgrading an existing unsubscribed team.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, indicating a safe read operation. The description adds value by specifying that it returns the 10 most recent notes, which is behavioral context beyond annotations. No contradictions.

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 extremely concise with two sentences, no fluff, and front-loads the core purpose. Every sentence contributes useful information (what it returns and the required parameter).

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 (one required parameter, clear annotations), the description is complete. It explains what the tool returns (details plus 10 recent notes). No output schema exists, but the return value specifics are covered. Sibling tools provide context for when to use this tool vs teams-list.

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 the single parameter. The description restates the required parameter without adding additional meaning or format details beyond what the schema provides. 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 that the tool retrieves team details including the 10 most recent notes, with a specific verb and resource. It distinguishes from sibling tools like teams-list by focusing on a single team's details.

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 specifies the required parameter 'id' (integer). While it does not explicitly state when not to use or list alternatives, the context of sibling tools and the simple nature of the operation provide implicit guidance. Could be slightly improved by mentioning that this is for getting a specific team, not listing all teams.

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 goes beyond annotations by disclosing that it sends an email invitation, requires the invitee to accept from that exact address, and that a per-seat charge is incurred only upon acceptance. Annotations indicate readOnlyHint=false and destructiveHint=false, which the description appropriately supports.

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, front-loading the core purpose and then adding key details. No 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?

For a simple tool with two parameters and no output schema, the description covers the action, prerequisites, side effects (charge only on acceptance), and exact behavior (must accept from exact email). Nothing 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 coverage is 100% with descriptions for both parameters. The description adds that team_id can be obtained from teams-list, which is helpful but not essential. The additional context is minimal beyond what the schema provides.

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 (invite), the target (teammate to a team by email), and the restriction (team owner only). It distinguishes itself from sibling tools like teams-list or teams-get.

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 mentions the prerequisite (team owner) and required parameters, and notes that the invitee must accept from the exact email. It does not explicitly state when not to use this tool or mention alternatives, but the 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying exactly what data is returned (members_count, notes_count, containers_count), which is not in 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?

Single sentence, no wasted words. Efficiently conveys purpose, scope, and returned fields.

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 zero parameters and no output schema, the description is sufficiently complete. It covers the action, scope, and returned data. Minor lack of guidance on ordering or filtering, but acceptable for a simple listing.

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% (empty parameters). Description adds no additional parameter meaning beyond stating no parameters are required, which matches the schema.

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

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

Clearly states the action (list), resource (teams), scope (user is a member of), and additional fields returned (members_count, notes_count, containers_count). Distinguishes from sibling tool 'teams-get' which retrieves a single team.

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 states 'No parameters required' which implies simplicity. No explicit when-not-to-use or alternative suggestions, but the tool is straightforward, and sibling tools (e.g., teams-get) are available for different use cases.

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