hjarni

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

Beyond annotations (readOnlyHint=false indicates a write operation), the description adds useful behavioral details: it explains that parent_id null or root id results in top-level creation and that the response reports parent_id null, and it clarifies that the root is not a folder. It also states the constraint that team_id and parent_id must belong to the same team. These nuances are not in the annotations and help the agent understand edge cases and response semantics.

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 core action and then systematically explains each parameter. While it is longer than strictly necessary, every sentence adds value (e.g., root id nuance, team constraint, follow-up suggestion). It is structured logically from required to optional parameters, and the final recommendation to use instructions-update is a useful pointer.

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 five parameters, no output schema, and sparse annotations, the description covers all parameters, explains edge cases (root id, team scoping), and even suggests a follow-up action. It does not explicitly state the return value (e.g., that it returns the created container), but it does mention response behavior for parent_id. Given the lack of an output schema, a note on the return format would improve completeness, but the description is already quite thorough.

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

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

The schema already covers all five parameters with descriptions (100% coverage). The tool description goes beyond the schema by elaborating on negative_space (what does not belong, how it routes notes) and clarifying parent_id behavior (null/omitted vs root id, response behavior). It also adds the team_id–parent_id constraint that is not present in the schema. These additions meaningfully improve parameter understanding.

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

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

The description opens with a specific verb and resource: 'Create a new container (folder) for organizing notes.' It clearly distinguishes the creation action from sibling tools like containers-update or containers-delete by naming the action explicitly. Even without naming alternatives, the purpose is unambiguous and the function of the tool is immediately obvious.

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

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

The description implies when to use the tool (when a new container is needed) but does not explicitly contrast with alternatives like containers-update or containers-list. It does provide usage context such as team_id constraints and the parent_id nesting logic, which helps guide correct invocation. However, it does not state when NOT to use this tool or name sibling tools explicitly, so it falls short of full guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context: the delete is a move to Trash, it carries sub-folders and notes as one recoverable unit, it is restorable for 30 days, and it permanently removes afterward. No contradiction with annotations.

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

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

The description is front-loaded with the core action and recoverability, then gives the important alternative and permissions. The final 'Required: id (integer)' sentence is redundant given the schema, but overall it is 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?

For a destructive one-parameter tool with no output schema, the description covers the action, recoverability window, permanence, alternative behavior, permissions, and required parameter. Nothing material is missing for an agent to call it correctly.

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

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

Schema coverage is 100% for the single required id parameter, so the schema already documents its meaning. The description repeats 'Required: id (integer)' but adds no format or semantic detail beyond the structured field.

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

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

States a specific verb and resource — moving a folder to Trash — and clarifies scope, contents, and recoverability. It distinguishes itself from containers-update's archived behavior and explicitly names containers-restore as the reversal path.

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 and when-not-to-use guidance: use this for real deletion that leaves every listing, but use containers-update with archived: true to retire a folder while keeping it browsable in the Archive. It also states the editor-role requirement for team folders.

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, so the safety profile is covered. The description adds real behavioral value beyond this: the response contents (including the negative_space semantic 'what does NOT belong in the folder'), the include_tree expansion behavior (ancestor chain and children), and the root:true special-case behavior. It omits error behavior (e.g., what happens when id does not exist), but with annotations carrying the safety burden, the added context is strong.

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 core action is front-loaded in the first sentence, followed by response contents, then optional parameters, then the root-container caveat. The root:true warning earns its place — it prevents an agent from wasting a call on containers-update. The paragraph is dense but every clause carries information; it is slightly long but justified by the semantic richness.

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 compensates by enumerating the key return fields, covering the special root case, and providing sibling routing. For a read-only single-get tool with only two parameters, this is largely complete. It does not mention error handling for nonexistent IDs or permission requirements, but these are minor against the readOnlyHint=true and idempotentHint=true annotations.

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

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

Schema description coverage is 100%, so both id and include_tree are already documented in the schema. The description restates 'Required: id (integer)' and explains include_tree as 'also get ancestor chain and children,' which largely mirrors the schema's 'Include ancestors and children arrays (default: false).' The negative_space clarification concerns the response object rather than parameters, so the description adds only marginal value beyond the schema — baseline 3 applies.

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

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

The description opens with a specific verb+resource+scope: "Get a single container by ID," and enumerates the exact fields returned (notes_count, children_count, description, negative_space, LLM instructions), which distinguishes it from the sibling containers-list tool that retrieves collections. It also clarifies the notable root: true special case, sharpening exactly what entity this tool targets.

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 single-by-ID phrasing implicitly separates it from containers-list, and it explicitly names containers-update as the tool that refuses root containers, routing the agent to instructions-update for that edge case. It does not explicitly state 'use containers-list instead when you need multiple containers,' leaving that primary alternative unspoken, but the routing guidance it does give is precise 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?

Annotations already declare read-only and non-destructive, but the description adds substantial behavioral context: pagination details, shared container inclusion, root folder exclusion, and scope-specific behavior (including 'trashed' with restores_with counts). This goes far 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 information-dense, with each sentence covering a distinct aspect (return format, pagination, scopes, root behavior). It is well-structured and front-loads the core purpose before diving into details, though it could be slightly tightened.

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 listing tool with no output schema, the description is remarkably complete: it specifies the return format (JSON array plus pagination line), explains all scope nuances, covers shared containers and root exclusion, and addresses edge cases like 'trashed'. Nothing essential 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 covers all parameters (100%), so baseline is 3. The description adds extra meaning: root container behavior, shared containers auto-inclusion, and explanation of the 'trashed' scope with restores_with. This enhances understanding beyond the schema's simple 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 tool lists containers (folders) for notes and specifies that each container includes notes_count and children_count. It is distinct from sibling tools like containers-get (single container) and containers-create, 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 explains the tool's behavior and scopes but does not explicitly say when to use this tool versus alternatives like containers-get. It lacks direct 'use this when' or 'not for' guidance, though the purpose is clear enough for an agent to infer basic 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true) by disclosing cascade semantics ('Roles cascade to descendants unless a child has its own role'), the team-owner protection rule ('Team owners are always admin and cannot be downgraded'), and the admin authorization requirement. There is no annotation 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?

Dense and largely waste-free, with each sentence carrying a distinct constraint. The purpose sentence arrives after the scope sentence, which is slightly less front-loaded than ideal, but no sentence is redundant.

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

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

For a 3-param mutation tool with no output schema, the description covers authorization, cascade behavior, inherit semantics, protection rules, and the return value ('the user's resulting effective_role'). Nothing an agent needs to call it 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 coverage is already 100%, yet the description adds genuine meaning: 'inherit' is explained as deleting an explicit role and falling back to the ancestor/team-membership role, and it constrains container_id to a team container and user_id to a same-team member. This is value beyond the raw enum. Baseline 3 is exceeded.

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

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

States a specific verb and resource ('Set or clear a team member's role on a team container') and immediately bounds scope ('Change access only for existing members of the same Hjarni team'). It distinguishes itself from siblings like teams-invite by declaring 'this does not invite anyone or publish a folder'.

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 the when-not conditions ('does not invite anyone or publish a folder') and the prerequisite ('Caller must have admin role on the target container'). It also names the triggering intent ('Change access only for existing members'), leaving little to inference.

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 and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior: the cascade semantics (sub-folders and notes return together as they were), which the annotations do not convey. This is useful, though it stops short of noting reversibility window or failure modes.

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 action and cascade effect, then discovery path, then the notes-restore exclusion, then the required parameter. Every sentence carries information, though the parenthetical about notes-restore is slightly verbose.

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 annotations covering safety, a single fully-described parameter, and no output schema to explain, the description supplies everything needed to call correctly: cascade semantics, how to discover valid ids, the sibling exclusion, and the required argument.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already documents 'id'. The description's '(integer, the deleted folder's id)' and 'Required' largely restate the schema, adding little beyond it. Baseline 3 applies.

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

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

States a specific verb+resource ('Restore a deleted folder from Trash') and the scope (personal account or authorized team workspace). It also distinguishes itself from the sibling notes-restore by explaining the cascade case, 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?

Explicitly routes the agent to containers-list with scope 'trashed' to find restorable folders, and names the condition under which notes-restore will refuse and this tool is the only path. Both when-to-use and the alternative are stated.

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

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

Annotations only declare the safety profile (destructiveHint=true, idempotentHint=true); the description adds substantial behavior beyond that: root refusal, the editor-role requirement for team containers, the include_notes/include_nested bulk semantics, the response containing containers_changed and notes_changed counts, and a detailed caveat that an unarchive sweep resurrects individually-archived items and reactivates ancestor folders.

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-loads the core action and scope before the operational details, and every sentence carries real information. It is dense and long, with some repetition around archiving semantics, but nothing is truly wasted given the mutation's complexity.

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

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

For a 9-parameter destructive mutation with no output schema, it covers prerequisites (editor role), edge cases (root refusal, ancestor reactivation), reversal caveats, and even the response shape (containers_changed/notes_changed). An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine inter-parameter semantics the schema lacks: parent_id null (not the root's id) for top-level, negative_space null clears the field, and how archived combines with include_notes/include_nested. This meaningfully exceeds the per-field schema docs, though individual field definitions largely mirror 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?

Opens with a specific verb and resource ('Update a folder within the connected user's personal Hjarni account or an authorized team workspace') and enumerates every supported operation: rename, description/negative_space, move parent, position, archive/unarchive. It explicitly distinguishes itself from siblings by naming containers-get, instructions-update, and notes-update as the correct tools in specific situations.

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 and when-not-to-use guidance: refuses the space root and routes the agent to instructions-update, and says to pass parent_id null rather than the root's id. It also gives a strong alternative-routing rule ('never loop notes-update over each note') and a conditional fallback for selective unarchiving.

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 cover the safety profile (readOnlyHint false, idempotentHint false, destructiveHint false), but the description adds real behavioral context beyond them: mail-to-note conversion, subject-as-title, attachments carried across, and the crucial security caveat that the address is a secret anyone can write to the folder with. That is exactly the extra context the annotations 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?

Front-loads the purpose, then behavior, then parameters, then an imperative reminder. It is a single dense paragraph but each clause carries information; the parenthetical parameter list is slightly verbose but not wasteful.

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?

There is no output schema, yet the description explains the return concept ("the returned address") and how it should be handled, and it documents every parameter's effect. For a creation tool with three optional params, this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, giving a baseline of 3. The description nonetheless adds semantics beyond the schema, notably that tags are added alongside an automatic 'email' tag and that label becomes the first part of the generated address.

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

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

States a specific verb and resource ("Create an email capture address") and immediately explains the mechanism (mail becomes a note in a folder). It is easily distinguishable from the sibling email-addresses-list.

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

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

The description explains what the tool does and gives an operational instruction ("Tell the user the address once..."), but it never states when to use this versus related creation tools like notes-create or containers-create, nor any prerequisites. Usage is implied rather than guided.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: empty-array return when none exist, the meaning of accepting_mail: false (mail currently being dropped), and a security warning that each address is a write credential for its folder. That last point is a genuine operational constraint an agent would otherwise miss.

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?

Purpose is front-loaded and the following sentences each carry load (return fields, edge cases, security). The enumerated field list is slightly long but justified since no output schema exists to document the response.

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 compensates by enumerating the returned fields (id, label, address, destination, container_id, team_id, tags, notes_count, last_received_at) and documenting the empty-array and accepting_mail edge cases. Nothing an agent needs to call and interpret this tool is missing.

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

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

The tool takes zero parameters, so the schema is trivially complete and there is nothing to disambiguate. Baseline 4 applies for a no-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?

States a specific verb and resource ('List the user's email capture addresses') and immediately explains what those addresses do, distinguishing this read tool from the sibling email-addresses-create. An agent knows exactly what it retrieves without opening any 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?

Usage is implied by the listing semantics, but there is no explicit guidance on when to reach for this versus email-addresses-create or other container/folder tools, and no stated prerequisites. Minimum viable: the verb makes the context obvious, nothing more is provided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutating, non-repeatable nature is partly signaled. The description adds genuinely new context: the email notification 'cannot be recalled' and the requirement to include only user-authorized details. It stops short of spelling out auth/permission requirements, so it is strong but not exhaustive.

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 purpose and irreversibility before the when/when-not guidance, and every sentence carries routing or constraint value. It is dense and slightly repetitive of the schema's parameter documentation, which keeps it from 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?

For a non-idempotent submit action with no output schema, the description covers purpose, triggering conditions, exclusions, and the irreversibility of the side effect. It omits any explicit statement of required permissions or what the confirmation response looks like, minor gaps for this tool class.

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

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

Schema coverage is 100%, so the schema already documents every parameter, enum, and the default. The description largely restates the enums and default and adds only marginal framing ('what's wrong and ideally what you'd expect instead', 'error excerpts, the arguments you tried'), which overlaps with the schema's own examples. Baseline 3 is correct 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?

States a specific verb and resource ('Send feedback to Hjarni's maintainers') and clarifies the downstream effect (stores a record, emails an admin notification). It explicitly scopes what the feedback is about ('about Hjarni itself — confusing tool descriptions, missing capabilities...') and names the sibling it is not for ('notes-create'), so it is distinguishable from the large sibling list without opening a 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 explicit when ('use only when the user asks to send feedback') and when-not ('Do NOT use this for the user's own notes or knowledge — those belong in notes-create') plus an authorization constraint ('include only the task-specific details they authorized'). The alternative tool is named directly, leaving nothing to inference.

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 cover openWorldHint=true, idempotentHint=false and destructiveHint=false, but the description adds behavior they cannot express: follows up to three redirects, the url-vs-file precedence rule, blank-placeholder handling, and hard prohibitions (never invent URLs, pass local paths, or base64-encode bytes). For a non-idempotent open-world fetch, these are exactly the operational facts an agent needs.

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?

Dense but appropriately front-loaded: source and scope come first, then constraints, then optional overrides, then the fallback. Every sentence carries information, though the 'never invent them / local path / base64' sentence and the ChatGPT-supplied-URL sentence overlap slightly and could be tightened.

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 a 6-parameter tool including a nested file object and no output schema, the description covers sources, precedence, redirects, overrides, and the fallback tool well. The one gap is what the call returns (attachment identifier or file record), but that is a minor omission given how thoroughly the invocation path is specified.

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, but the description goes beyond the per-field text by defining resolution order ('If both sources are supplied, a non-empty file reference takes precedence; an all-blank file placeholder is ignored') and default derivation for filename and content_type from reference metadata or the HTTP response. Only the note_id parameter gets no added 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?

States a precise verb and resource ('Fetch a file from a public URL or a native ChatGPT file reference and attach it to one of your personal notes') and immediately bounds scope to personal notes, naming the sibling (files-create_upload_url) that handles team/shared notes. An agent can distinguish this from files-attach and files-create_upload_url without opening a 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?

Explicit when-to-use (public URL or ChatGPT file reference, personal notes), when-not (team or shared notes → files-create_upload_url), a preference rule ('in ChatGPT, prefer file'), and a fallback ('When no reference or public URL is available, use files-create_upload_url'). Alternatives and selection conditions are fully specified.

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 already declare the mutation/non-idempotent profile, but the description adds substantial context: 30-minute expiry, max_files_per_upload and max_file_size_bytes limits, batch constraints via remaining_bytes/remaining_files, and the rationale for token savings. This goes well beyond the structured fields.

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 and the share-the-link instruction before the caveats. Every sentence is functional, though it is dense and runs long; a hair more structure would help but nothing 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?

An output schema exists, so return values need not be explained. The description covers expiry, limits, batch constraints, the drop-zone uncertainty, and the verification path, which is complete for a two-parameter 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 note_id and description are already documented in the schema. The description merely restates 'Required: note_id' and 'Optional: description' without adding format or semantic meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Generate a one-time upload link') and resource ('attaching files to a note'), and implicitly distinguishes itself from siblings like files-attach and files-attach_from_url by describing a browser-based upload path. An agent knows exactly what this tool produces.

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 to share the upload_url with the user, explains why (token savings), handles the ambiguous drop-zone case, and names files-check_upload as the follow-up verification step. When-to-use and the alternative are both spelled out.

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 cover read-only, idempotent, non-destructive, but the description adds behavior the structured fields cannot: the response echoes resolved_level and defaulted_level (with semantics of when it is true), container returns the full inheritance chain outermost-first with per-entry level fields, and agent tokens additionally receive agent_instructions with a brain_instructions_off flag. That is substantive disclosure of return semantics and edge cases.

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 action and the primary recommended invocation, and every clause carries information (defaults, requirements, inheritance ordering, agent-specific fields). It is dense and passes over semicolon-joined clauses that could be split, but there is no filler.

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

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

No output schema exists, and the description nonetheless describes the response shape (resolved_level, defaulted_level, inheritance chain, agent_instructions). All parameters are covered in schema and description, no required params, and the level-specific routing gaps are closed.

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 would be 3, but the description goes beyond the schema by tying id to specific levels (required for 'container' and 'team'), clarifying that 'container' accepts a personal or shared container id, and flagging that team container ids are not addressable here. That adds real selection 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?

States a specific verb+resource ('Get LLM instructions') and immediately scopes it by level, which is the tool's distinguishing axis versus instructions-update. An agent can identify the resource, the enumeration of levels, and the default without opening the 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 explicit when-to-use guidance ('Call with level "brain" early in conversations to learn user preferences') and names alternatives with the condition that selects them: team container ids route to notes-get or level 'team'. Both the trigger and the exclusions are stated.

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

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

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 cover read-only/idempotent/non-destructive, but the description goes further: it discloses that the user's email is exposed while billing and token metadata are not, documents the exact return fields (onboarding.completed, onboarding.missing_steps with its enum values), and warns that the `nudge` field is frequency-capped and must be handled per the server's NUDGES section. That is meaningful behavior beyond the annotation set.

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

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

Front-loaded with the purpose, then rationale, then return shape, then privacy scope. Every sentence carries distinct information (when to call, what comes back, what is withheld, how to treat the nudge); no filler or restatement of the title.

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 must carry the return contract, and it does: it enumerates the returned fields, gives the missing_steps enum values, and explains the optional nudge. It also clarifies the privacy boundary. An agent has everything needed to call and interpret 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?

Zero parameters, so the baseline of 4 applies. The description confirms 'No parameters required,' which matches the empty schema and prevents an agent from hunting for an implicit user identifier.

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 concrete verb plus a bundle of specific resources (profile, onboarding state, team memberships, note quota) and frames them as a single call. Nothing in the sibling list overlaps with this 'current user' scope, so an agent can immediately tell it apart from teams-list, dashboard-get, or 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?

Explicitly instructs 'Call this once at the start of a conversation' and gives the downstream conditions the result powers: greet by first name, run the onboarding script only when needed, route notes to the right team space, avoid suggesting unavailable features. This is genuine when-to-use guidance with an implicit don't-repeat constraint from 'once'.

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 cover safety (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds real value beyond them: server-enforced write access, quota notifications that email owners and cannot be recalled, and the initial status ('active'). It does not reconcile why a create tool carries destructiveHint=true, which leaves one small gap.

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-loads the operation and scope, then constraints, then optional params and an example. Dense and mostly waste-free, though the parameter recap and example add length that partly duplicates the schema.

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

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

For an 8-parameter creation tool with no output schema, it covers access requirements, side effects, defaults, and per-parameter intent well. Return-value behavior is only partially addressed via the 'starts verified (status active)' remark.

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 goes beyond the schema by stating a convention the schema does not enforce ('always include a 2-3 sentence summary ... even though the schema only enforces title') and by clarifying that review_after is only for notes that should flag themselves stale.

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

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

States a specific verb and resource ('Create a note') plus the scope of targets (personal account, shared folder, team workspace), which cleanly separates it from notes-update, notes-get, and notes-list. It even names the sibling workflow to prefer when a note already exists.

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 routing: 'Search for an existing note on the topic first and update that instead when there is one,' which points at notes-search/notes-update. It also gives conditional guidance for individual parameters (team_id for team creation, review_after only for time-boxed notes).

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

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

Annotations declare destructiveHint=true, but the description goes well beyond them: it explains the operation is recoverable, that body/attachments/history are retained, the default 30-day purge window, the role requirement, and the shared-container restriction. This is exactly the contextual nuance a mutation tool needs.

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-loads the recoverability constraint and permission scope, which is the right ordering. Slightly redundant — the recoverability idea is stated twice ('restorable with notes-restore' and 'can be undone with notes-restore'), costing a 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?

For a single-parameter delete tool with no output schema, all an agent needs is present: what it does, recovery path, purge window, role/auth constraints, and the blocked case. Nothing material 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?

Only one parameter (id) and schema coverage is 100%, so the schema already carries full meaning. The description merely restates 'Required: id (integer)' and adds no format or source guidance, so baseline 3 applies.

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

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

States a specific verb+resource ('Move a note to Trash') and scopes it to personal vs authorized team workspaces. The recoverable-not-erase framing immediately distinguishes it from any hard-delete expectation and it names the sibling (notes-restore) it pairs with.

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 it works ('your own personal notes and team notes where you have the editor role') and when it does not ('You cannot delete notes in a shared container (only the owner can)'). It also names the alternative for undoing — notes-restore — with the purge-date window.

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 readOnly/idempotent/non-destructive, and the description adds substantial behavioral detail beyond them: trashed notes return a status:'trashed' summary with purge deadline instead of content, missing brain entry means no custom instructions, and inherited_instructions ordering is outermost-first.

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 verb and return contents, then layers edge cases (trash, missing brain). It is dense but nearly every clause carries information; the inherited_instructions explanation is slightly long but earns its place for an editing workflow.

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 and does so: it describes the return payload, the trash-summary exception, and instruction-layer semantics. An agent has everything needed to call and interpret the result.

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?

Only one parameter with 100% schema description coverage, so the schema already documents 'id'. The description's 'Required: id (integer)' merely restates the schema with no added syntax or meaning; 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 states a specific verb (get) and resource (a single note by ID) and enumerates exactly what the return includes: full Markdown body, tags, container path, linked notes, backlinks, attachments, and inherited_instructions. This clearly distinguishes it from siblings like notes-list and notes-search_mentions.

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

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

It gives concrete usage context — the inherited_instructions payload means 'no separate instructions lookup is needed before editing' — and routes trashed notes to notes-restore. It stops short of an explicit when-not or a named alternative for the single-note read case, but the operational guidance 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 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the panel fallback for clients without panels, the full return shape, and the concurrency-control requirement to use expected_lock_version from the latest read before notes-update. This is behavior an agent cannot infer from 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?

Purpose and trigger lead the description, followed by return shape, then fallback, then mutation caution. Dense but every sentence carries actionable information; only the trailing 'Optional: id (integer)' is redundant with the schema.

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

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

With no output schema, the description compensates by naming the returned fields and the degraded-mode response, and it covers the edit/optimistic-lock workflow. Nothing an agent needs to call it 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?

Only one optional parameter with 100% schema coverage, and the schema already documents the omit-id picker behavior. The description restates the same semantics ('Without an id the panel opens on a note picker') without adding format or constraint detail beyond the schema, so the structured data is doing the work.

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

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

States a specific verb and resource (open a note in the Hjarni note panel beside the conversation) and explains exactly how it differs from notes-get by enumerating the extra fields (space, can_edit, uri). An agent can distinguish it from notes-get, notes-panel and notes-list without opening any 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 explicit trigger conditions (user asks to open, show or work on a specific note) plus a prerequisite workflow (find the id with search first) and a follow-on constraint (pass expected_lock_version from your latest read before notes-update). Covers when to use it and what to do next.

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 it as destructive/non-idempotent; the description adds real behavioral detail beyond them: optimistic-locking semantics for 'get', 'save' and 'toggle' (unchanged/stale/conflict statuses), the fact that a stale lock_version 'saves nothing', the line-diff and merge_hunks conflict resolution path, and that 'purge' deletes for good. This is exactly the concurrency and irreversibility context an agent needs for a mutating tool.

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

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

The critical routing warning is correctly front-loaded in the first two sentences, but everything after is one dense, unbroken block enumerating 32 actions with no line breaks or hierarchy. For a mega-tool some enumeration is warranted, yet the format makes scanning for a single action costly.

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 33-parameter dispatcher with no output schema and destructive annotations, the description supplies the key missing pieces: the action inventory, parameter-to-action mapping, and concurrency/conflict behavior. What it does not describe is what most actions return, which is a real but secondary gap given the size of the surface.

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 is 3. The description nonetheless adds per-action grouping (which params belong to which action) and a non-obvious cross-parameter rule not present in the schema: 'search' with an id returns only the notes that note can link to. It stops short of documenting return shapes or the remaining per-action combinations, so it is above baseline but 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 opening sentence states exactly what the tool is and who it is for ('Used only by the Hjarni note panel UI to reload, preview and save the note it shows'), and it names the sibling tools an assistant should use instead (notes-get, notes-update). An agent can distinguish this from every other notes-* sibling without opening a 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?

It gives an explicit negative rule ('Assistants should not call this') plus concrete alternatives for the two use cases an agent would otherwise pick this for (read via notes-get, edit via notes-update). This is the strongest form of routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so safety is largely covered. The description adds real behavioral context beyond that: what is restored (body, tags, attachments, history), the purge-date time limit, and the account/workspace scope.

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?

One dense front-loaded sentence states scope, effect, and precondition, followed by the required-parameter line. Slightly redundant with the schema's own required marker, but no wasted sentences.

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

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

For a one-param, annotation-covered mutation with no output schema, the description covers what is restored, the purge-date constraint, and the target account scope. The only missing piece is explicit routing versus notes-revert.

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 single param is documented there, so baseline is 3. The description goes further by specifying that id is the same note id produced by notes-delete, which is meaningful semantic guidance for retrieving the right value.

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

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

States a specific verb (Restore) and resource (note) with its origin (moved to Trash by notes-delete) and account scope. An agent can distinguish this from notes-delete and, on inspection of the name, from notes-revert without opening any 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 a clear applicability condition — only works before the note's purge date — and identifies the parameter needed (the id of the deleted note). However, it does not contrast with the sibling notes-revert, leaving the agent to infer which of the two recovery tools to pick.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavioral context: this endpoint is restricted to the @-mention picker and returns selectable resources with space and folder subtitles. It does not cover auth or rate limits, but those are not clearly needed here.

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

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

The description is appropriately sized and front-loads the critical usage restriction before naming the alternative. The final sentence repeating the query parameter is redundant with the schema, slightly reducing efficiency, but overall it remains tight.

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 low complexity, rich annotations, 100% schema coverage, and an output schema, the description contains everything an agent needs. It explains the specialized use case, points assistants to the correct alternative, and does not need to describe return values because the output schema exists.

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 documents that the query string may be empty to return recently edited notes. The description repeats this same information, adding no extra syntax, format, or edge-case meaning beyond the schema. A 3 is the baseline when the schema already carries parameter 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 states a specific verb and resource: returns notes matching a typeahead query as selectable resources. It also distinguishes this tool from the sibling `search` tool by explicitly telling assistants to use `search` instead. This is clear enough to identify the tool without opening the 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?

It gives explicit when-to-use context (only the ChatGPT composer's @-mention picker) and an explicit alternative for assistants (`search`). The exclusion is unambiguous, leaving no inference needed about when this tool is appropriate.

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?

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false); the description goes well beyond by disclosing the 3-free-team quota, the exact error shape, and the instruction to relay rather than retry. It also documents the return payload (join_url, join_link_expires_at, join_link_uses_remaining) in the absence of an output 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?

Purpose and ownership come first, then parameter guidance, then the failure mode and return value. Every sentence carries non-redundant information with no filler despite the density.

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 compensates by describing return fields, and it also covers the quota-exhaustion error path and the sibling routing. Nothing an agent needs to call this 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 coverage is 100%, so the baseline is 3; the description nonetheless reinforces the enum meaning of 'ref' with surface-level context ('SOLELY when creating in response to the offer') that the schema text states more tersely. The name parameter is only restated, so credit is marginal rather than substantial.

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 ('Create a new team') and adds the ownership consequence ('they become the owner'), which is behaviorally meaningful. It also implicitly distinguishes itself from the sibling teams-invite by assigning self-join to this 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?

Gives explicit when-to-use for the ambiguous 'ref' parameter (only when responding to the me → suggestions.create_team offer) and an explicit exclusion (omit when unprompted). It names the alternative teams-invite and the exact condition that selects it (user names a specific address).

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?

Adds substantial behavior beyond the annotations: notes it is team-owner-only (auth requirement), warns that 'Creating a link REPLACES any existing one' (matching destructiveHint/idempotentHint=false), and instructs the agent never to post the link itself. This enriches the destructiveHint=true signal with the specific resource that gets invalidated.

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?

Information-dense and front-loaded, with the mode split and required parameter stated first. It runs long, but nearly every clause carries operative detail (mode selection, replacement warning, sharing rule) rather than 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?

With no output schema, the description compensates by naming the returned fields (join_url, join_link_expires_at, join_link_uses_remaining) and warning about link replacement. An agent has everything needed to call it and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: email omission switches to link mode, action defaults to 'create', and 'revoke' removes the link. It also explains the side effect of 'create' (invalidating prior links), which the schema only hints at.

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

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

States a specific verb and resource ('Get a teammate into a team') and enumerates the two operating modes (with email vs. without). It explicitly references team_id provenance (from teams-list) and distinguishes itself from teams-get by explaining read vs. create semantics for join 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?

Gives an explicit default preference ('Prefer the LINK unless the user names an address') with a rationale, and names the alternative path (read join_url from teams-get to re-share rather than re-minting). This is actionable when/when-not guidance rather than implied context.

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.