hjarni

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

Annotations only supply generic hints (readOnly=false, idempotent=false, etc.), so the description carries the behavioral burden. It discloses create semantics, top-level versus nested creation, team-scoping constraints, and the negative-space routing behavior, adding meaningful context beyond the annotations. No contradiction exists.

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 dense but efficiently organized: it front-loads the purpose, then groups parameters by required/optional, explains nesting and team scope, and ends with a useful next-step pointer. Every sentence contributes practical information without filler.

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

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

For a tool with no output schema, the description does not mention the return value, which is a minor gap. However, it fully covers invocation requirements: required name, optional fields, top-level/null semantics, team/parent constraint, and a follow-up action. This is enough for correct selection and calling.

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 mostly restates what the schema already says for name, description, negative_space, parent_id, and team_id. It adds a little framing around negative_space and same-team parent_id, but doesn't substantially enhance the parameter semantics beyond the schema.

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

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

The description opens with 'Create a new container (folder) for organizing notes,' a specific verb and resource that clearly distinguishes it from siblings like containers-update, containers-delete, and containers-list. It also points to instructions-update as a related follow-up, further differentiating it from other 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?

It clearly states when to use the tool—to create a new container—and describes required versus optional inputs, personal versus team scope, and the parent_id same-team constraint. It does not explicitly say 'use containers-update for existing containers,' but the create-only context is unambiguous enough for an agent to select appropriately.

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 were provided, so the description carries the full burden, and it fully discloses: the operation is a real delete (not just a status change), moves content to Trash as one recoverable unit, permanently deletes after 30 days, and requires an editor role. This is rich, honest behavioral disclosure.

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, front-loaded with the core behavior trailing into details, exclusions, and permission requirements. The final 'Required: id (integer)' is redundant with the schema, so not a perfect 5.

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 destructive operation with cascading effects.The description covers what happens (trash, one unit, permanent after 30 days), alternatives, caveats, and permissions. No output schema exists, but return values are not essential for a delete action.

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?

Input schema already documents id as required integer with 100% coverage. The description repeats 'Required: id (integer)' but adds no new meaning beyond the schema. 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 opens with a specific verb+resource: 'Move a folder to the Trash, taking its sub-folders and notes with it as ONE recoverable unit.' It clearly distinguishes itself from containers-restore (restoring from trash) and containers-update (archiving) by explicitly labeling this as a real delete.

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 versus an alternative: 'to retire a folder while keeping it in the Archive, use containers-update with archived: true instead.' It also gives a precondition (editor role on every folder) for using 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?

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?

Beyond the readOnly/idempotent annotations, the description reveals important non-obvious behavior: the response is a JSON array followed by a summary line, shared folders are appended in full on the first page, and totals are reported separately. These details materially change how an agent should parse and interpret results.

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

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

The description is front-loaded with the core purpose and keeps all important behavioral details in four sentences. The optional-parameter sentence is slightly redundant with the schema, but it remains compact and useful as a summary rather than becoming bloated.

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

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

For a list tool with four optional parameters, no output schema, and annotations already covering safety, the description covers everything an agent needs: item shape, return format, paging totals, shared-container handling, team scope, and filter options. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a small amount of value by noting the default scope ('roots') and team semantics, but it largely repeats the schema and even omits the 'trashed' enum value that the schema documents. The schema remains the primary source for parameter meaning.

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

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

The description clearly identifies the operation ('List containers') and the resource ('folders for organizing notes'), and adds what each item contains (notes_count, children_count). It does not explicitly contrast with sibling tools like containers-get or notes-list, but the resource specificity is strong enough for an agent to select it correctly.

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 team_id versus personal containers, scope options, and how shared containers behave when listing root-level personal containers. It does not explicitly state when not to use this tool or name alternatives, so it falls short of a full 5, but the usage context is concrete and actionable.

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

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

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 already carry idempotentHint=true and destructiveHint=false; beyond that the description adds real context — restoration is atomic for the folder's subtree ('sub-folders and notes return together, exactly as they were') and that the notes-restore path refuses such notes. Nothing contradicts the 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 earning its place: purpose and scope, discovery path, sibling exclusion, and required parameter. Front-loaded with the core verb-resource pair and zero filler.

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

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

For a one-required-parameter restore tool with no output schema, everything needed to select and invoke correctly is present: what is restored, how to locate eligible targets, how it interacts with notes-restore, and exactly what id to pass.

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 schema already describes id as 'Deleted container ID (required)'. The description adds only the minor clarification that it is 'the deleted folder's id,' so the baseline 3 applies without meaningful additional semantics.

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

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

The description opens with a specific verb and resource — 'Restore a deleted folder from the Trash' — and sharply defines the scope by saying the whole deleted subtree comes back together. It also names the sibling it is not (notes-restore), so an agent can distinguish it without opening another schema.

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

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

Gives an explicit precondition and discovery path ('Find restorable folders with containers-list scope ‘trashed’') and an explicit exclusion: a note deleted together with a folder can only come back this way because notes-restore refuses it. When-to-use and when-not-to-use are both stated directly.

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?

Although annotations already flag destructiveHint and idempotentHint, the description discloses the real behavioral consequences: bulk cascade, reactivation of previously archived notes and sub-folders, ancestor-reactivating behavior on unarchive, role requirements, and the fact that note bodies are not returned. It also specifies the containers_changed and notes_changed response counts, going well beyond the 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?

Though longer than average, the description is well structured and every sentence earns its place. It front-loads the core operation, then groups required/optional parameters, bulk archiving behavior, permissions, response counts, and reversal caveats in a logical order. The explicit 'never loop notes-update' guidance is high-value and prevents an obvious misuse.

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 complex 9-parameter, destructive, no-output-schema tool, the description is unusually complete. It covers scope constraints, editor-role requirements, bulk side effects, reversal caveats, response counts, and alternatives. An agent has enough information to decide whether and how to call this tool safely.

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 schema already contains descriptions, so the baseline is 3. The description adds meaningful semantics on top: negative_space accepts null to clear it, parent_id null means root and must remain in the same scope, position uses lower-as-first, and include_notes/include_nested interact with archived to produce cascading effects.

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

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

The description opens with a specific verb and resource: 'Update an existing container' and then enumerates the exact updateable aspects — rename, description, negative_space, parent, position, and archive state. It clearly differentiates from sibling create/delete/list/restore tools by focusing on mutation of an existing container.

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

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

It explicitly states when to use the bulk archive path ('This is THE way to retire a whole folder... never loop notes-update over each note') and when to unarchive selectively. It also identifies role requirements for team containers and points to containers-list scope 'archived' as the way to find archived folders later.

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 only show read-only=false and destructive=false, but the description adds meaningful behavioral detail: mail becomes a note, subject becomes the title, attachments carry over, an automatic 'email' tag is added, and the address is a secret anyone can write to. This goes well beyond the annotation hints.

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 core action arborea, then presents behavior, parameters, and a safety warning in a compact logical order. No filler or repetition of the title beyond the first sentence.

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

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

Covers purpose, parameter behavior, side effects, and a security warning for the user. It does not describe the exact response shape, but the instruction to 'tell the user the address once' implies the address is returned, which is sufficient for 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%, but the description adds extra meaning: null/omitted container_id routes to the Inbox, label forms the first part of the address, and tags are combined with an automatic email tag. These are not fully explicit in 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 uses a specific verb and object—'Create an email capture address'—and immediately explains the core behavior: anything mailed to the address becomes a note in the chosen folder. It also flags the Pro-only restrictionhol and distinguishes this creation tool from the sibling email-addresses-list 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?

The description gives clear context for when to use the tool by explaining what it does, its Pro-only limitation, and the resulting side effect of incoming mail becoming notes. It does not explicitly contrast it with alternatives, but the creation purpose is unambiguous and the sibling list tool is not a plausible substitute.

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, and the description appropriately matches a non-destructive read. It adds important behavioral disclosure beyond annotations: the security warning that each address is a write credential for a folder and must not be placed in notes or summaries. This is valuable context the agent needs for downstream actions, not just for this 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 compact yet information-dense: a clear action, the Pro restriction, the behavior, the return-field list, the Free-account behavior, and a security warning all fit in four sentences. The most actionable warning about secrecy is placed at the end with emphasis, and no sentence is wasted.

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

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

Given zero parameters, no output schema, and annotations already covering safety/idempotence, the description is fully complete for invocation. It even provides return-field names and the Free-account empty-array case, which are exactly the context an agent needs to interpret results correctly. There is no missing information for selecting or calling this 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?

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameter syntax. The description does, however, enumerate the return fields (id, label, address, destination, container_id, etc.), which meaningfully describes what the agent can expect in results even without an output schema. This exceeds the baseline for a zero-parameter tool.

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

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

The description names a specific verb ('List') and resource ('the user's email capture addresses'), and immediately clarifies it is Pro-only. It distinguishes the read/list behavior from sibling creation tools like email-addresses-create, so an agent can tell them apart without opening schemas.

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

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

The description provides clear context: mail sent to these addresses becomes a note in a bound folder, and Free accounts get an empty array. It also states when not to expect data, effectively guiding an agent selecting this tool versus alternatives. Although it doesn't name explicit alternative tools, the sibling list already contains email-addresses-create, and the description's focus on listing makes the usage context 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description doesn't need to restate those. The description adds useful behavioral context: it explains what kind of content is expected, that severity defaults to 'medium', and that context can be a JSON-encoded string. It doesn't describe side effects (e.g., whether feedback is stored, emailed, or anonymous), but the annotations cover the safety profile and the description adds meaningful context beyond them.

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 front-loads the purpose and usage guidance, then lists parameters. It's efficient and every sentence earns its place, though it could be slightly more scannable with line breaks. No fluff or repetition.

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 feedback-submission tool with 5 parameters, 100% schema coverage, and no output schema, the description is complete enough. It covers what to submit, when to use it, what not to use it for, and parameter semantics. The only minor gap is not describing what happens after submission (e.g., confirmation, storage), but that's not essential for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds value by explaining the intended use of 'message' ('what's wrong and ideally what you'd expect instead'), clarifying 'tool_name' with an example, and noting that 'context' is a JSON-encoded string. It also states the required parameters and the default for severity, which goes beyond the schema.

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

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

The description states a specific verb ('Submit feedback'), a clear resource ('about Hjarni itself'), and explicitly distinguishes from notes-create ('Do NOT use this for the user's own notes or knowledge'). It also lists concrete example categories, making the tool's purpose unmistakable.

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 when to use this tool ('when something about the MCP server, a tool, or the product behavior is worth flagging') and when NOT to use it ('Do NOT use this for the user's own notes or knowledge — those belong in notes-create'). It also names the alternative tool, which is strong 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 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?

Annotations are sparse (all false hints), so the description carries the full burden and delivers extensively: 30-minute expiry, per-request file counts, per-file size caps, the batch constraint when remaining_bytes/remaining_files are present, and the nuance that some clients render a drop-zone the agent cannot detect. This is precisely the kind of behavioral context an agent needs and the structured fields do not 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?

Content is dense and front-loaded: purpose, token rationale, expiry, limits, and follow-up verification all earn their place. The only waste is the final 'Required: note_id (integer). Optional: description.' line, which duplicates the input schema instead of adding value. Trimming that would make it a 5.

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 an output schema exists (so return values need no explanation), an output-type proof is a simple tool with 2 parameters is essentially complete: it covers purpose, key operational behavior (expiry/limits), client rendering nuance, safety (expiry), and the verification handoff. Nothing an agent needs to invoke and use the result correctly is left out.

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 both parameters already have clear descriptions in the schema. The description only restates them ('Required: note_id (integer). Optional: description.'), adding no new semantics such as value ranges, formats, or why description matters. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

Opens with a specific verb+resource+context: "Generate a one-time upload link for attaching files to a note." This cleanly separates it from its files-* siblings (files-attach, files-attach_from_url, files-get_download_url, files-remove) since it is the only one producing a client-side upload URL. An agent knows exactly what this tool is for without opening any sibling schema.

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

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

Gives clear when-to-use context: share the link so the user uploads in their browser, explicitly because it 'saves tokens by avoiding base64 encoding,' and names the follow-up tool files-check_upload for verification. It also instructs that the link must always be shared because drop-zone rendering is undetectable. It doesn't explicitly name the alternative (e.g., files-attach_from_url) and when to choose it over this tool, which keeps it just shy 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds crucial behavioral context: URL expiry (15 minutes), no-login access, and treating it as a credential. This goes beyond annotations with no contradiction.

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 with zero filler. The core purpose is front-loaded, and the expiry/security note is concise. Every sentence earns its place.

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

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

Complete for a low-complexity tool with fully documented parameters and helpful behavioral notes. The description mentions the response field (download_url_expires_at) even though there is no output schema, covering the return behavior adequately.

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 descriptions for both parameters. The description adds value by specifying that file_id comes from notes-get response, which is not in the schema, and reiterates the required relationship. This is a slight enhancement over the 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?

States a specific verb+resource: 'Get a time-limited download URL for a file attached to a note.' It clearly differentiates from sibling file operations (attach, remove, upload) and includes the intended use case (share with user).

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: when to use (to download in browser) and practical guidance (request fresh URL instead of reusing old). Lacks explicit exclusions or alternatives, but the purpose is narrow enough that no alternative is needed.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral detail beyond that: defaulting behavior and the response fields (resolved_level, defaulted_level), the inheritance chain ordering, and the limitation on team container ids. This gives the agent confidence in what to expect and how to interpret results.

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

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

The description is a single compact paragraph, but it is information-dense and every sentence adds value. It is not as scannable as a bulleted format, but the structure is logical: purpose, usage tip, parameter details, and a caveat. Slightly long but justified by the richness of content.

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

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

With no output schema, the description carries the full burden of explaining the response. It describes the response echoes (resolved_level, defaulted_level) and details the inheritance chain format for 'container' (level field, outermost first). It also covers edge cases like team container ids. Nothing an agent needs to call this tool correctly is missing.

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

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

While the schema already documents both parameters and their enums, the description enriches their meaning significantly. It explains how 'id' interacts with 'level' (required for container and team, not for brain), elaborates on the container inheritance returned, and clarifies that team container ids are not valid here. This goes well beyond the schema's basic 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 verb ('Get'), the resource ('LLM instructions'), and specifies the levels ('brain', 'personal_root', 'container', 'team'). It also implies the distinction from sibling tools like notes-get by focusing on the instruction hierarchy. This is a specific, unambiguous purpose that an agent can act on.

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?

Explicit guidance is provided: 'Call with level brain early in conversations to learn user preferences.' It also gives when-not-to-use by pointing to alternatives: team container ids cannot be addressed here, and the agent is directed to notes-get or level 'team'. This level of direction fully equips the agent to choose the correct 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), 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 mark the tool read-only, idempotent, and non-destructive, so the description builds on that by revealing return details: onboarding.completed and onboarding.missing_steps types, the optional frequency-capped nudge, and the explicit statement that billing/token metadata is not exposed. This is meaningful behavioral context beyond the 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 long but every sentence adds value: purpose, when to call, return values, nudge behavior, and data-scope caveats. It is front-loaded with the core purpose buck. It could be slightly tightened, but no filler is present.

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

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

With no output schema, the description carries the burden of explaining return semantics and does so well: onboarding.completed, onboarding.missing_steps with allowed values, the optional nudge and how to handle it, and the privacy boundary of not exposing billing/token metadata. It also gives the exact call timing ('once at the start of a conversation'). This fully equips an agent to invoke and interpret the 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?

The tool takes zero parameters and the schema description confirms 'No parameters required.' Per the rubric, 0 params is a baseline 4; the description also restates this clearly, so no additional parameter meaning is 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 opens with a specific verb and resource: 'Get the connected user's profile, plan, onboarding state, team memberships, and note quota in a single call.' This precisely defines what the tool does and enumerates the data it returns, leaving no ambiguity about its purpose. The reference to 'connected user' clearly identifies the resource scope.

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 instructs when to call: 'Call this once at the start of a conversation' and explains why—greeting by first name, running onboarding, routing notes, and avoiding Pro upsells to free users. This is concrete usage guidance that an agent can act on immediately, even without a sibling 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?

Annotations only mark readOnlyHint false, etc., offering no behavioral detail. The description compensates by disclosing that a new note starts with status 'active' and that summary is required by convention even though the schema only enforces title. It also explains wiki-link syntax and the meaning of review_after. This adds value beyond annotations and 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 well-structured with 'Required', 'Optional', and an example. It front-loads the purpose, then lists parameters with clear usage hints, and ends with a concrete example. Every sentence adds value, and the length is justified given the 8-parameter 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 create operation with 8 parameters and no output schema, the description covers all necessary operational details: required title, summary convention, optional parameters with usage context, the resulting status, and an example. An agent can call this correctly without additional information.

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 descriptive comments, so baseline is 3. The description adds extra meaning: it highlights that title is required, summary is required by convention, review_after is only for time-boxed notes, and team_id controls the target space. This goes beyond simple schema text, earning a 4.

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 'Create a new note', a specific verb+resource pair, and the name notes-create reinforces it. It distinguishes itself from sibling tools like notes-update, notes-delete, and notes-list by explicitly stating it creates, and the surrounding text adds scope (personal vs. team, containers, tags).

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

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

It clearly states when to use it (to create a note) and gives conditional guidance: use team_id for team creation, only set review_after for time-boxed notes, and always include a summary. It does not explicitly contrast with alternatives like notes-update for editing, but the context is unambiguous for a creation 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?

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 (readOnlyHint, idempotentHint, destructiveHint false) already cover the safety profile. The description goes much further by disclosing the Trash edge case (returns a status summary instead of content), the inherited_instructions semantics (outermost-first, inbox carries brain plus space root), and the missing-brain fallback behavior. This is far beyond what annotations 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 long (several dense sentences) but every sentence delivers a specific fact: return field list, instruction-layer semantics, brain-fallback, Trash behavior, and required parameter. It is front-loaded with the core purpose, so the verbosity is earned rather than padded.

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

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

With no output schema and only one simple parameter, the description must carry the full explanation of what is returned and how edge cases behave. It covers the complete return field list, the Trash summary shape, and the missing-brain fallback to instructions-get. Nothing an agent needs to call it correctly is omitted.

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 parameter id is fully documented in the schema as 'Note ID (required)'. The description only repeats this as 'Required: id (integer)' and weaves id into the purpose, adding no new meaning such as format constraints, valid ranges, or id-related behavior. Baseline 3 is correct.

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

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

Opens with 'Get a single note by ID' and names the full content bundle (Markdown body, tags, container path, linked notes, backlinks, attachments, inherited_instructions), making it clearly distinct from notes-list, notes-restore, and instructions-get. The phrase 'so no separate instructions lookup is needed' explicitly differentiates it from the instructions-get sibling.

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 concrete routing: trashed notes are summarized and should be restored via notes-restore before reading/editing, and missing brain entries fall back to instructions-get with level 'brain'. It does not explicitly state 'use this instead of notes-list when you need one note by ID', but the ID-focused purpose implies this clearly, so it earns a 4 rather than 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?

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?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses concrete behaviors: it returns a paginated JSON array, then a line with the total match count and whether more pages remain. It also explains that `include_body` and `include_instructions` are withheld for trashed notes, and that `include_instructions` defaults to `include_body` — useful nuance not visible in the schema alone.

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 long, but it is front-loaded with the core purpose and use-case distinction, then moves into parameter details. Each sentence adds information (pagination, onboarding fallback, combos), and the example at the end aids comprehension. A few repetitions exist (e.g., the note about being withheld for trashed notes appears twice), but overall it's dense and structured, not flabby.

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 13 parameters (0 required), full schema coverage, and no output schema, the description compensates thoroughly: it explains the output shape (array + total-count line), pagination mechanics, when to use include_body to avoid extra calls, and the empty-result onboarding path. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter and its meaning. The description adds value beyond that by explaining interactions (e.g., `container_id` can combine with `team_id`), the default of `include_instructions`, the `include_body` trade-off, and a concrete example (`{container_id: 5, tags: ['ruby']}`). This is more than a baseline 3, though it doesn't radically change any single param's semantics.

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

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

The description opens with a specific verb ('List and browse') and a clear resource ('the user's saved notes'), then enumerates what those notes are. It explicitly distinguishes itself from the sibling tool `search` ('Use search instead when hunting for a topic or keyword; use this to enumerate a folder, tag, or scope'), so an agent can immediately tell them apart.

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 when-to-use guidance: it names the alternative (`search`) and the condition that selects it (topic/keyword hunting vs. enumeration). It also tells the agent what to do when the result is empty (call `me` and follow onboarding.next_action), which is a clear usage directive beyond mere selection.

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?

The description is exceptionally transparent about mutation, revisions, lock_version behavior, destructive snippet replacement, and the append-only idempotency caveat. However, it directly contradicts the annotation idempotentHint=true by stating that append-only calls are not replay-protected and that retrying an identical append can append the text twice. Per the rubric, a direct contradiction with annotations requires a score of 1.

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

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

The description is long but appropriately so for a 27-parameter tool. It is logically organized into required params, body-mutation modes, markdown operations, organization, tags, concurrency, and examples, with the core purpose front-loaded and every sentence contributing functional guidance.

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 highly complex mutation tool with no output schema, the description is remarkably complete. It covers concurrency safety, destructive behavior, permissions around archiving, mutual exclusions, matching constraints, and provides concrete examples for the trickiest operations. An agent has enough context to invoke the tool correctly in nearly every documented scenario.

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?

Although schema coverage is 100%, the description adds substantial semantic value beyond the schema: body-mutation modes are grouped and marked mutually exclusive, tag_list precedence over add_tags/remove_tags is stated, 'body wins' over surgical modes is explicitly disclosed, anchor uniqueness rules are explained, and expected_lock_version gets detailed concurrency semantics including the append-only exemption.

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

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

The description opens with a specific verb and resource—'Update a note'—and immediately enumerates the distinct actions available: edit content, move folder, archive/favorite, change tags. It explicitly positions itself as the tool for moving notes between folders and notes that there is no separate move tool, clearly differentiating it from sibling tools like containers-update and notes-create.

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 strong contextual guidance: it names this as the move tool, explains when to supply expected_lock_version, and points to notes-history and notes-revert for auditing/undoing. It does not systematically contrast with every sibling mutation tool, but it provides enough routing and scenario-based guidance for an agent to select it correctly.

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 idempotentHint=true and destructiveHint=false. The description adds behavioral context: it stops appearing on all surfaces and acts on the user's behalf. No contradictions. Lacks disclosure of potential side effects beyond dismissal, but the annotation covers the safety profile adequately.

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 the main action, followed by precise usage conditions and parameter requirement. Every sentence is essential and no redundant 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 one parameter and no output schema, the description covers purpose, usage guidelines, parameter source, idempotency, and effect. No missing information that would hinder correct invocation.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter: 'The nudge key from the `me` payload's nudge block (required)'. The description merely restates this as 'Required: key (string, the `nudge.key` from `me`)', adding no new semantic value beyond what the schema already 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 'Dismiss a nudge served in the `me` payload' with a specific verb (dismiss) and resource (nudge from me payload). It distinguishes from ignoring nudges, and no sibling tool targets nudges, so differentiation is inherent.

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 'Call this ONLY when the user has actually declined the suggestion or asked not to be reminded — never on mere silence', providing clear when-to-use and when-not-to-use guidance, including rationale about server-side frequency capping.

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 mark this as read-only, idempotent, and non-destructive (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description goes beyond these by disclosing the default parameter behavior ('include_body' defaults to false), the branching logic for empty results, and the result grouping/pagination behavior — all genuinely useful for an agent deciding whether search will satisfy the task without side effects. The inclusion of the 'include_instructions' default tied to include_body and the empty-result onboarding guidance is unusually transparent. 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?

Front-loaded with the core purpose, then the key differentiator, then behavioral specifics, then parameters. It's long, but nearly every sentence adds operational value, and the alternatives/division between behavior and empty-state guidance is coherent. The parameter enumeration is dense but earned given the 16 parameters.

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

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

Covers the core use case, return grouping/pagination, result structure (include_body vs include_instructions), edge case behavior (empty results → call `me`), and parameter semantics like container_id being ignored when search_scope is team-wide. Combined with a rich schema and clear annotations, this is a complete operational picture.

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 covers all 16 parameters with descriptions, so baseline is 3. The description adds genuine value by clarifying the default behaviors (types default to all three, include_body default false, include_instructions defaults to include_body), the AND logic for tags, the ignored condition for container_id, and the semantics of inherited instructions. It doesn't fully explain every parameter, so not a 5, but it materially enriches the schema.

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

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

States a specific verb+resource ('Search across notes, containers, and tags') and immediately differentiates itself as the go-to tool for retrieving anything the user has previously saved, contrasting with sibling tools that manage those entities (e.g., containers-create, containers-update). The exhaustive list of content types makes the scope unmistakable, and the phrasing 'Returns results grouped by type' adds concrete output behavior an agent can rely on.

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?

Clearly establishes when to use the tool ('When a task needs something the user previously stored') and describes the fallback action when results are empty ('call `me` and follow onboarding.next_action'), which is a genuinely useful decision rule. However, it doesn't explicitly state when not to use it in favor of a specific sibling tool, so a 5 isn't earned, but the context provided is strong.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral detail by specifying the exact return format (JSON array plus summary line with total and pagination status), which goes beyond the 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 with no filler: the first states purpose and output shape, the second lists optional parameters. Information is front-loaded and every word earns its place.

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

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

For a simple read-only tool with no required params and no output schema, the description covers the essential behavior and output format. It does not mention pagination defaults or edge cases, but these are minor given the tool's simplicity.

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 page and per_page, each with basic descriptions. The tool description merely repeats their names and types without adding default values, ranges, or effects. This meets the baseline for high schema coverage but adds no extra guidance.

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

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

The description states the verb 'List' and resource 'tags' with the added detail of 'notes_count', making the tool's purpose specific and unambiguous. It clearly distinguishes from sibling tools like tags-create and tags-manage by describing a read-only listing operation.

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

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

The description implies usage for listing all tags but does not explicitly compare with alternatives or state when not to use it. Given the sibling set includes create/manage, an explicit routing note would improve clarity, but the intent is reasonably inferable.

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 the free-team limit, the error behavior at the limit, that no charge is incurred until a teammate accepts, and the response fields join_url, join_link_expires_at, and join_link_uses_remaining. It also tells the agent to relay the limit error rather than retry, which is valuable operational 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 longer than average, but every sentence carries operational value: purpose, required/optional parameters, charge semantics, limit errors, response fields, and routing to the sibling tool. It is front-loaded with the core purpose and keeps related concepts together.

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 there is no output schema, the description fully explains return values and their role. It covers edge cases, error handling, billing, and the alternative tool, making the agent's decision and invocation path complete without needing additional 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?

Schema coverage is 100%, and the description adds meaningful usage context for ref beyond the schema enum, specifying exactly when it must be set and when it must be omitted. The required nature of name is also reinforced with 'Required: name (string)'.

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

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

The description states a specific action ('Create a new team') and clarifies ownership ('they become the owner'). It also distinguishes itself from teams-invite by explicitly naming that sibling as the alternative for inviting named addresses.

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 guidance: use teams-invite when the user names a specific address. It also gives precise instruction on when ref must be set to 'assistant_suggestion' and when it must be omitted, leaving no ambiguity.

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 discloses substantial behavioral details beyond the annotations: creating a link replaces any existing one ('REPLACES any existing one'), the 'revoke' action removes it, and joining adds a billable seat. It also warns to give the link to the user, never post it. Annotations only indicate mutation (readOnlyHint=false), but the description adds crucial side effects and usage 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 long but logically structured, starting with purpose and required parameters, then modes, guidance, caveats, and pricing. Each sentence adds operational value with no repetition. Slightly verbose, but the density of information justifies the 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?

Covers all necessary context: permission (team owner only), both modes with their outputs (join_url, expires_at, uses_remaining), side effects (replacement, billing), and edge cases (reusing a shared link). The description is complete for an agent to call the tool correctly without an output schema.

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 the schema covers all three parameters, the description adds strategic semantic guidance: it explains the email vs. no-email decision, clarifies that 'action' only applies to link mode, and specifies that team_id comes from teams-list. This goes beyond simple schema definitions to guide the agent's parameter selection.

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 with a specific verb and resource: 'Get a teammate into a team'. It distinguishes two operational modes (email vs. join link) and explicitly notes the 'team owner only' permission. It also references sibling tool 'teams-list' for obtaining team_id, making it easy to differentiate from other team-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 explicit guidance on when to use the link vs. email: 'Prefer the LINK unless the user names an address'. Critically, it directs users away from this tool when repeating a shared link: 'read join_url from teams-get instead of calling this'. This is a clear, actionable alternative.

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.