hjarni
Server Details
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- hjarni/hjarni-mcp
- GitHub Stars
- 0
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.4/5 across 28 of 28 tools scored. Lowest: 3.9/5.
Each tool has a clearly distinct purpose: notes, containers, files, tags, teams, instructions, search, links, dashboard, feedback, and user info are all separate concerns. No two tools appear to perform the same function, even with the many notes-update body mutations.
Most tools follow a verb_noun pattern (e.g., notes-create, containers-list). However, 'me', 'search', and 'links-manage' break the pattern. 'me' and 'search' are single-word, and 'links-manage' uses a verb that doesn't match the typical noun-verb order. Overall mostly consistent.
28 tools is on the higher end, but the server covers a comprehensive note-taking domain with notes, containers, files, tags, teams, search, and more. Each tool earns its place, and the count feels justified for the feature set.
The tool set provides complete CRUD coverage for notes, containers, files, and tags, plus search, dashboard, team management, user info, instructions, and even a feedback tool. There are no obvious gaps for the stated purpose of a 'Second Brain' knowledge management system.
Available Tools
28 toolscontainers-createAInspect
Create a new container (folder) for organizing notes. Required: name (string). Optional: description (string), negative_space (string — what does NOT belong in this folder, so notes can be routed away from it), parent_id (integer) for nesting inside another container, team_id (integer) to create the container in a team instead of personal space. When team_id is set, parent_id (if provided) must belong to the same team. After creating, consider setting up LLM instructions with instructions-update.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Container name (required) | |
| team_id | No | Create container in this team instead of personal space | |
| parent_id | No | Parent container ID for nesting. Must belong to the same scope (personal or team) as the new container. | |
| description | No | Container description | |
| negative_space | No | What does NOT belong in this folder (e.g. 'No meeting notes, those go in Meetings'). Helps route notes away from the wrong place. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-destructive behavior. Description adds constraints like parent_id must belong to same team, and negative_space usage. No additional disclosure of side effects or auth requirements.
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, front-loaded purpose, parameter list, and a helpful post-action hint. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all required and optional parameters with constraints. No output schema, but description doesn't need to cover return values. Could add error handling hints but sufficient for the task.
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 for parameter descriptions. Description adds meaningful context beyond schema, e.g., negative_space explanation, parent_id scoping rule, and team_id usage.
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 container (folder) for organizing notes'. The verb 'Create' and resource 'container' are specific. Distinguishable from sibling tools like containers-get, containers-list, containers-update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies required and optional parameters, including team_id and parent_id constraints. Provides post-creation suggestion about instructions-update. Could explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
containers-getARead-onlyIdempotentInspect
Get a single container by ID, including notes_count, children_count, description, negative_space (what does NOT belong in the folder), and LLM instructions if set. Optional: include_tree (boolean) to also get ancestor chain and children. Required: id (integer).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID (required) | |
| include_tree | No | Include ancestors and children arrays (default: false) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, and the description adds useful behavioral details like returning notes_count, children_count, negative_space, and LLM instructions, plus the optional include_tree parameter. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with a clear list of returned fields. It is concise and front-loaded with the core purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully enumerates the fields returned, including the optional tree structure. For a simple get-by-ID tool, this is complete and adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds context beyond the schema: it specifies id is required and explains include_tree as 'ancestor chain and children'. This adds value but is not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single container by ID', specifying the verb and resource. It lists the fields returned and distinguishes from sibling tools like containers-list which would return multiple containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use (get a single container by ID). It lacks explicit when-not-to-use guidance, such as suggesting containers-list for multiple containers, but the purpose is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
containers-listARead-onlyIdempotentInspect
List containers (folders) for organizing notes. Each container includes notes_count and children_count. Optional: team_id (integer) for team containers, scope ('roots' default|'all'|'archived'), page, per_page. Shared containers are automatically included when listing root-level personal containers.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| scope | No | Filter scope (default: roots). 'archived' only for personal containers. | |
| team_id | No | List containers in this team instead of personal containers | |
| per_page | No | Results per page |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint, so the tool is safe. The description adds context about shared containers being automatically included and scope restrictions for 'archived'. It could mention pagination limits or ordering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, returned fields, and parameter notes. It is front-loaded with the core action and efficiently adds necessary details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and parameters adequately for a read-only list tool with no output schema. However, it lacks details on pagination behavior (default page size, ordering) and does not describe the full response structure beyond notes_count and children_count.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes all parameters. The description adds value by clarifying the default scope value and the restriction that 'archived' only applies to personal containers, which is not clear from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List) and resource (containers/folders) for organizing notes. It distinguishes this from sibling tools like containers-get (single) and containers-create by its listing purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains optional parameters (team_id, scope, page, per_page) and a special case for shared containers. However, it does not provide explicit guidance on when to prefer this over alternatives (e.g., containers-get for a single container) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
containers-permissionsADestructiveIdempotentInspect
Set or clear a team member's role on a team container. Roles cascade to descendants unless a child has its own role. Caller must have admin role on the target container. Required: container_id (integer, must be a team container), user_id (integer, must be a member of the same team), role ('viewer' | 'editor' | 'admin' | 'inherit'). Use 'inherit' to delete an explicit role and fall back to the role inherited from an ancestor (or from team membership). Team owners are always admin and cannot be downgraded. Returns the user's resulting effective_role on that container.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | New role, or 'inherit' to clear an explicit role (required) | |
| user_id | Yes | Team member's user ID (required) | |
| container_id | Yes | Team container ID (required) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds crucial behavioral details: roles cascade to descendants, 'inherit' clears explicit role, team owners cannot be downgraded. It also states the return value (effective_role). This fully informs the agent about side effects and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, with every sentence adding value. It is front-loaded with the main action and then adds details about behavior, requirements, and return value. No superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool that manages permissions with inheritance and specific constraints, the description covers all necessary context: cascading behavior, the meaning of 'inherit', required roles for the caller, and what is returned. No output schema exists, but the description fills that gap by stating the return value (effective_role).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions, but the tool description adds extra context: explains that 'inherit' is used to delete an explicit role, that container_id must be a team container, and user_id must be a team member. This goes beyond the schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set or clear a team member's role on a team container.' It specifies the verb (set/clear), resource (role on container), and distinguishes from sibling tools like containers-create or containers-get. Very clear purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to set or clear a role), provides context about behavior (cascading roles), and lists prerequisites (caller must have admin role, container must be team container, user must be a member of the same team). It does not explicitly name alternatives but implies that for other container operations, use other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
containers-updateADestructiveIdempotentInspect
Update an existing container — rename, change description or negative_space (what does NOT belong here), move to a different parent, or set display position. Works for both personal and team containers the current user can edit (team containers require the editor role). Required: id (integer). Optional: name, description, negative_space (pass null to clear it), parent_id (null for root, must be in the same scope), position (integer, lower = first).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID (required) | |
| name | No | New name | |
| position | No | Display order position (lower numbers appear first) | |
| parent_id | No | New parent container ID (null for root). Must belong to the same scope as the container. | |
| description | No | New description | |
| negative_space | No | What does NOT belong in this folder, or null to clear it. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=true. Description adds clarity on negative_space clearing via null but doesn't elaborate on other behavioral aspects like effect on children or permission requirements beyond editor role.
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 main actions, then parameter details. Information dense without redundancy. Slightly long but necessary for 6 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?
No output schema, so description could mention return value. Missing idempotency explanation. Given 6 params and no output schema, adequately covers usage but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3). Description adds meaning: explains negative_space concept, parent_id null for root and same scope constraint, position lower=first. Valuable extras 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?
Description clearly states it updates an existing container with specific actions (rename, change description, negative_space, move parent, set position). Distinct from create/get/list siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it works for personal and team containers with editor role. Notes required id and optional fields. Lacks explicit 'when not to use' but context from siblings covers this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
dashboard-getARead-onlyIdempotentInspect
Get an overview of the Second Brain: counts of notes, containers, tags, and inbox items, plus recent_notes (the 5 most recently created personal notes) and recent_changes (the 5 most recently edited notes across ALL spaces — personal, teams, and shared containers — newest edit first). Use recent_changes to orient at the start of a conversation on what changed lately everywhere. No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds rich behavioral details: counts, exactly 5 recent notes (personal), 5 recent changes (all spaces, newest first), and a use case. 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?
Two sentences, front-loaded with main purpose, no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description fully covers the expected output, including constraints on recent_notes and behavior of recent_changes, making it complete.
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. Baseline score of 4 applies as per guidelines for 0 parameters. Description confirms this with 'No parameters required.' and the schema is empty.
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 explicitly states the verb 'Get' and resource 'overview of the Second Brain', listing specific data returned (counts, recent_notes, recent_changes). It is distinct from sibling tools that handle specific resources like notes or containers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use the recent_changes field ('to orient at the start of a conversation'), but does not explicitly mention alternatives or when not 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.
feedback-submitAInspect
Submit feedback about Hjarni itself — confusing tool descriptions, missing capabilities, unexpected errors, friction, or praise. Use this when something about the MCP server, a tool, or the product behavior is worth flagging to the maintainers. Do NOT use this for the user's own notes or knowledge — those belong in notes-create. Required: category ('bug'|'confusing'|'missing_feature'|'friction'|'praise'|'other'), message (string, what's wrong and ideally what you'd expect instead). Optional: severity ('low'|'medium'|'high', default 'medium'), tool_name (the MCP tool the feedback is about, e.g. 'notes-update'), context (JSON-encoded string with any extra structured data — error excerpts, the arguments you tried, the workflow that broke).
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Optional extra context as a JSON-encoded string (e.g. error messages, arguments tried, related note IDs). Non-JSON strings are stored as plain text. | |
| message | Yes | The feedback itself. Be specific — describe what happened, what you expected, and (if relevant) what would have helped. (required, max 4000 chars) | |
| category | Yes | What kind of feedback this is (required) | |
| severity | No | How impactful this is for users (default: medium) | |
| tool_name | No | The MCP tool this feedback is about, if any (e.g. 'notes-update', 'search') |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no idempotent or destructive hints, so description carries burden. Description clarifies it's for system feedback, but doesn't mention side effects or storage. Additive but could state feedback is stored and reviewed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is thorough but slightly long. Front-loads purpose, then details parameters. No wasted sentences, but could be more concise by combining some sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description must explain what feedback submission entails. Covers all parameters and provides usage guidance. Minor gap: doesn't describe post-submission behavior (e.g., confirmation, storage).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, description adds significant value: explains category enum, gives defaults (severity default medium), clarifies context as JSON-encoded string with examples. Exceeds schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Submit feedback about Hjarni itself' with specific examples (confusing tool descriptions, missing capabilities). Explicitly distinguishes from sibling tool notes-create by stating what NOT to use it for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (for issues with MCP server, tools, product behavior) and when not to (user's own notes belong in notes-create). Provides alternative tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
files-attachAInspect
Attach a file to one of your personal notes via base64-encoded data (personal notes only; for team or shared notes use files-create_upload_url). Prefer files-create_upload_url for large files to save tokens. Required: note_id (integer), filename (string), data (base64 string). Optional: content_type (MIME type, default: application/octet-stream), description.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Base64-encoded file contents (required) | |
| note_id | Yes | Note ID (required) | |
| filename | Yes | Filename (e.g. report.pdf) (required) | |
| description | No | Optional file description | |
| content_type | No | MIME type (e.g. application/pdf). Defaults to application/octet-stream |
Tool Definition Quality
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.
files-attach_from_urlAInspect
Fetch a file from a public URL and attach it to one of your personal notes (personal notes only; for team or shared notes use files-create_upload_url). Follows one redirect. Required: note_id (integer), url (string). Optional: filename (default: derived from URL), content_type (default: from HTTP response), description.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | URL to fetch the file from (required) | |
| note_id | Yes | Note ID (required) | |
| filename | No | Override filename (default: derived from URL) | |
| description | No | Optional file description | |
| content_type | No | Override MIME type (default: from HTTP response) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show read/write, non-destructive, non-idempotent. Description adds that tool follows one redirect and defaults for filename and content_type. Could mention error handling or overwrite behavior, but overall good context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence states purpose and scope, second lists parameters. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple attach-from-URL tool with no output schema and 5 parameters fully described, the description covers all necessary context: purpose, scope, parameters, and redirect behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description enumerates each parameter with required/optional status and default behaviors, providing value beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Explicitly states 'Fetch a file from a public URL and attach it to one of your personal notes', with specific verb+resource. Distinguishes from sibling 'files-create_upload_url' for team/shared notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (personal notes only) and when-not-to-use (team/shared notes), naming the alternative tool. Also notes redirect behavior and required vs optional parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
files-check_uploadARead-onlyIdempotentInspect
Check the status of a file upload created by files-create_upload_url. Returns status: 'pending' (not uploaded yet), 'completed' (file attached, includes file metadata), or 'expired' (link timed out). Required: token (string, from files-create_upload_url response).
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | Upload token from files-create_upload_url response (required) |
Tool Definition Quality
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.
files-create_upload_urlAInspect
Generate a one-time upload URL for attaching a file to a note. Share this URL with the user so they can upload directly in their browser — saves tokens by avoiding base64 encoding. The link expires after 30 minutes. Use files-check_upload to verify completion. Required: note_id (integer). Optional: description.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | Note ID to attach the file to (required) | |
| description | No | Optional file description |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description adds behavioral details: one-time URL, 30-minute expiration, token savings, and required note_id. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each adding value: purpose, token savings, expiration, follow-up, and parameter requirements. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description provides sufficient context (expiration, follow-up) for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters. The description merely restates required/optional, adding no new semantics beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it generates a one-time upload URL for attaching a file to a note, with specifics on token savings and expiration. It distinguishes itself from siblings like files-attach and files-check_upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells when to use (to attach files with token savings) and mentions the follow-up tool (files-check_upload). However, it does not explicitly state when not to use or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
files-get_download_urlARead-onlyIdempotentInspect
Get a temporary download URL for a file attached to a note. Share the URL with the user to download in their browser. URL expires after a few minutes. Required: note_id (integer), file_id (integer, from notes-get response).
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | File ID from notes-get response (required) | |
| note_id | Yes | Note ID (required) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. The description adds transparency about the URL being temporary and expiring 'after a few minutes', which is not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. The first sentence states the purpose, the second provides usage guidance, and the third lists required parameters and key behavioral detail (expiration).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema, but the description fully covers the return value (a temporary download URL) and its lifetime. Required parameters are explicitly listed, making the description complete for a simple retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters. The description adds semantic value by specifying that file_id should come from 'notes-get response', which helps the agent select the correct value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'temporary download URL for a file attached to a note'. It distinguishes this tool from sibling file tools like files-attach and files-remove by focusing on URL retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to 'Share the URL with the user to download in their browser' and notes the URL expiration. While it doesn't explicitly state when to not use this tool, the action is singular and no alternative exists among siblings, so guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
files-removeADestructiveInspect
Permanently remove a file attachment from one of your personal notes (personal notes only). This action is irreversible. Required: note_id (integer), file_id (integer, from notes-get response).
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | File ID from notes-get response (required) | |
| note_id | Yes | Note ID (required) |
Tool Definition Quality
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.
instructions-getARead-onlyIdempotentInspect
Get LLM instructions at the specified level. Call with level 'brain' early in conversations to learn user preferences. Optional: level ('brain'|'personal_root'|'container'|'team'), defaults to 'brain' if omitted or blank; the response echoes resolved_level and defaulted_level (true when the level was defaulted). Optional: id (integer, required for 'container' and 'team' levels). 'container' level returns the full inheritance chain (personal root -> ancestors -> container).
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Container ID or Team ID (required for 'container' and 'team' levels) | |
| level | No | Instruction level: 'brain' (global), 'personal_root', 'container', or 'team'. Defaults to 'brain' if omitted or blank. | brain |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, idempotent, non-destructive. Description adds context about defaulting behavior, inheritance chain for container level, and response fields (resolved_level, defaulted_level), going beyond annotation info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences covering purpose, usage, and parameter details. Well-structured and informative, though slightly verbose in explaining default behavior. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return structure (resolved_level, defaulted_level, inheritance chain). Covers all parameter functions and usage contexts. Adequately complete for a getter tool with strong annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, baseline 3. Description adds meaning: explains default behavior for level (defaults to brain), and that id is required for container/team, elaborating on schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get LLM instructions at the specified level' with specific verb 'Get' and resource 'LLM instructions'. It distinguishes from siblings like instructions-update by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends calling with level 'brain' early in conversations to learn user preferences. Explains behavior for different levels and parameter requirements, though does not provide explicit when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
instructions-updateADestructiveIdempotentInspect
Update LLM instructions at the specified level. Required: level ('brain'|'personal_root'|'container'|'team'), instructions (string). Optional: id (integer, required for 'container' and 'team'), mode ('replace' default|'append'). The 'container' level updates personal containers only; to set instructions for a team, use level 'team' (team owners only). In 'replace' mode (default), the provided text overwrites existing instructions. In 'append' mode, the text is appended to existing instructions with a newline separator. Always read current instructions first before replacing to avoid losing existing content.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Container ID or Team ID (required for 'container' and 'team' levels) | |
| mode | No | Update mode: 'replace' (default) overwrites existing instructions, 'append' adds to them | |
| level | Yes | Instruction level to update (required) | |
| instructions | Yes | The instructions text. In 'replace' mode (default), this overwrites existing instructions. In 'append' mode, this is appended to existing instructions. |
Tool Definition Quality
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.
links-manageADestructiveIdempotentInspect
Create or remove a bidirectional link between two notes. Required: action ('link'|'unlink'), source_note_id (integer), target_note_id (integer). Prefer wiki-link syntax [[id:Title]] in note bodies for inline linking — use this tool for programmatic links without modifying body text. Unlinking is destructive and cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action: 'link' to create a link, 'unlink' to remove it (required) | |
| source_note_id | Yes | First note ID (required) | |
| target_note_id | Yes | Second note ID (required) |
Tool Definition Quality
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.
meARead-onlyIdempotentInspect
Get the connected user's profile, plan, onboarding state, team memberships, and note quota in a single call. Call this once at the start of a conversation so you can greet the user by first name, run the onboarding script only when needed, route notes to the right team space, and avoid suggesting Pro features to free users. Returns onboarding.completed (boolean) and onboarding.missing_steps (array of 'connect_mcp' | 'first_note'), which together tell you what, if any, setup is left. Exposes the user's email address and plan — same data the user sees in account settings, but never billing or token metadata. No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context beyond these: it specifies the precise data returned (onboarding.completed, onboarding.missing_steps, email, plan) and explicitly states what is NOT returned ('never billing or token metadata'). This full disclosure helps the agent understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) but packs significant detail: purpose, usage recommendation, specific data fields, and limitations. It is front-loaded with the primary action, then usage context, then details. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description fully explains what the tool returns (profile, plan, onboarding state with specific fields, email, team memberships, note quota) and explicitly states what it excludes. Given the tool's simplicity (no parameters), this is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and description states 'No parameters required.' With 100% schema coverage (none), the description doesn't need to add parameter semantics. Baseline 4 is appropriate; no additional value needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the connected user's profile, plan, onboarding state, team memberships, and note quota in a single call.' This specifies the verb (Get), resource (connected user's profile, plan, etc.), and distinguishes it from sibling tools (e.g., notes, containers, teams) which deal with different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to 'Call this once at the start of a conversation' and explains how the returned data can be used: greet user by first name, run onboarding script when needed, route notes, avoid Pro features for free users. Also notes that no parameters are required. This provides clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes-createAInspect
Create a new note. Required: title (string). Always include a 2-3 sentence summary too (required by convention, even though the schema only enforces title) so the note is useful to future LLM sessions. Optional: body (Markdown with [[id:Note Title]] wiki-links), summary, source_url, container_id, tag_list (comma-separated), team_id (to create in a team), review_after (ISO 8601 datetime, only set this for time-boxed notes that should flag themselves stale after a date). A new note starts verified (status 'active'). Example: {title: 'Meeting Notes', body: '## Agenda\n...', container_id: 5, tag_list: 'meetings, q4'}.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Note body content (Markdown with [[id:Note Title]] wiki-links) | |
| title | Yes | Note title (required) | |
| summary | No | A 2-3 sentence summary of the note. Always provide one. | |
| team_id | No | Create note in this team instead of personal space | |
| tag_list | No | Comma-separated list of tags (e.g., 'ruby, rails, testing') | |
| source_url | No | Source URL reference | |
| container_id | No | Container ID to place the note in | |
| review_after | No | Optional ISO 8601 datetime after which the note should be treated as stale. Use for time-boxed notes (e.g. '2026-12-31'). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that notes start with status 'active' (beyond annotations). Does not contradict annotations (readOnlyHint=false etc.). No mention of auth or rate limits, but annotations lower the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is moderately concise and well-structured, front-loading purpose and listing parameters with caveats. Not overly verbose, but could be more scannable (e.g., bullet points).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all 8 parameters and gives usage tips, but lacks details about return value (e.g., note ID). With no output schema, this is a notable gap. Otherwise adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value: explains summary is required by convention, tag_list is comma-separated, review_after for time-boxed notes, and provides an example. Exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new note' and specifies the required parameter (title). It lists optional parameters and distinguishes from sibling tools like update/delete, but could contrast more explicitly with current and related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides some usage guidance (summary required by convention, review_after for time-boxed notes) but does not explicitly state when to use this tool vs alternatives like notes-update or containers-create. Lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes-deleteADestructiveInspect
Permanently delete a note. This action is irreversible — the note and all its file attachments are destroyed. Works on your own personal notes and on team notes where you have the editor role. You cannot delete notes in a shared container (only the owner can). Required: id (integer).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Note ID (required) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals critical behavioral traits beyond the annotations: irreversible deletion of notes and file attachments, and role-based permissions (editor vs. owner). This adds significant context that the annotations (destructiveHint: true) alone 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?
The description is highly concise, using two sentences to convey all necessary information. The main action is front-loaded in the first sentence, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, no output schema, and comprehensive annotations, the description fully covers the tool's behavior: irreversible deletion, attachment destruction, and access restrictions. There are no obvious 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?
The input schema covers 100% of parameters, with the 'id' parameter already described as 'Note ID (required)'. The description merely echoes this requirement, adding no new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (permanently delete a note) and identifies the specific resource. The tool name and title also align, distinguishing it from other note tools like create, update, and 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 provides explicit guidance on when to use the tool (own notes, team notes with editor role) and when not (shared container, only owner can delete). It also highlights irreversibility, implying cautious use. However, it does not explicitly contrast with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes-getARead-onlyIdempotentInspect
Get a single note by ID, including its full Markdown body, tags, container path, linked notes (outgoing), backlinks (incoming links from other notes), file attachments, and inherited LLM instructions. Required: id (integer).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Note ID (required) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description need not repeat these. It adds useful behavioral context by detailing the returned data (e.g., 'inherited LLM instructions'), which goes beyond annotations. There is no contradiction. It could mention what happens if the ID is invalid, but the annotations provide sufficient safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the purpose and required input, then lists outputs. It is front-loaded with the core action ('Get a single note by ID'). Every phrase earns its place; there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple read operation with strong annotations (readOnlyHint, idempotentHint) and no output schema, the description sufficiently covers what is returned. It does not address error cases or pagination (not applicable). It is complete enough for effective use, though a brief note on error behavior would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' has schema description 'Note ID (required)'. The tool description repeats this as 'Required: id (integer).' With 100% schema coverage, the description adds no additional meaning about the parameter format, constraints, or example values. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single note by ID' and enumerates the specific content returned (Markdown body, tags, container path, linked notes, backlinks, file attachments, inherited LLM instructions). This distinguishes it from sibling tools like notes-list (which lists multiple notes) and notes-create/update/delete (which modify notes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states 'Required: id (integer)', which is necessary for usage. It implicitly clarifies that you use this tool when you have a specific note ID. However, it does not explicitly state when not to use it (e.g., for listing multiple notes use notes-list) or provide alternatives, which would improve guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes-listARead-onlyIdempotentInspect
List notes with optional filtering, sorting, and pagination. Returns paginated results. Optional: team_id (integer) to list team notes, scope ('active'|'archived'|'inbox'|'favorited'), container_id (integer) with include_nested (boolean), tags (array of strings, AND logic), tag_ids (array of integers, AND logic), summary_stale (boolean, filter to notes with outdated summaries), stale (boolean, filter to notes whose freshness is stale — past their review_after date or unverified for a while), sort ('recent'|'oldest'|'title'), page (integer, default 1), per_page (integer, max 100, default 25). container_id can be combined with team_id to list a specific team container. Example: list ruby-tagged notes in a container: {container_id: 5, tags: ['ruby']}.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| sort | No | Sort order: 'recent' (updated_at desc, default), 'oldest' (updated_at asc), or 'title' (alphabetical) | |
| tags | No | Filter to notes with ALL these tags by name (AND logic). Example: ['ruby', 'rails'] | |
| scope | No | Filter scope (default: active). 'inbox' and 'favorited' only for personal notes. | |
| stale | No | Filter to notes whose freshness is stale — past their review_after date or unverified beyond the freshness window (default: not filtered) | |
| tag_ids | No | Filter to notes with ALL these tags by ID (AND logic) | |
| team_id | No | List notes in this team instead of personal notes | |
| per_page | No | Results per page, max 100 (default: 25) | |
| container_id | No | Filter by container ID | |
| summary_stale | No | Filter to notes with outdated summaries (default: not filtered) | |
| include_nested | No | Include notes from sub-containers when container_id is set (default: false) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds valuable behavioral details like pagination, stale filter semantics, and parameter interactions, which go 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?
Well-structured: first sentence states purpose, then parameter list, then example. Slightly verbose but every sentence adds value. Front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 11 parameters and no output schema, the description fully explains all parameters, their interactions, defaults, and provides an example. Complete for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds significant meaning: explains AND logic for tags, scope restrictions, stale filter definition, and provides an example. This is well beyond the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists notes with optional filtering, sorting, and pagination. It distinguishes from sibling tools like notes-get, notes-create, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on parameters, including scope restrictions (inbox/favorited only for personal notes) and combination rules (container_id with team_id). An explicit alternative for single note retrieval is not stated but implied by tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
notes-updateADestructiveIdempotentInspect
Update a note: edit its content, move it to a different folder (set container_id, or null for the inbox), archive/favorite it, or change its tags. This is the tool for moving notes between folders; there is no separate move tool. Required: id (integer). Optional content (exactly one body-mutation mode at a time): title, body (full replace), append_body (appends to existing body), insert_after + insert_body (insert text immediately after a unique anchor snippet from the existing body), insert_before + insert_body (insert before a unique anchor), replace_find (+ optional replace_with) (replace a unique snippet; omit replace_with entirely to delete the snippet). Markdown-structure ops (heading/section/checklist aware — safer than eyeballing a unique snippet on long notes): replace_section + section_body (replace everything UNDER a heading, keeping the heading line); append_to_section + section_body (add content at the END of a section — the safe 'insert under heading' when you don't know its last line); rename_heading + new_heading (rename a heading in place, preserving its level unless new_heading carries its own '#'); check_item / uncheck_item (tick/untick a checklist item by its text, e.g. '- [ ] ship it'). Headings and checklist items must each match exactly one line. Anchor and find snippets must match exactly once; include enough surrounding context to disambiguate. Also optional: summary, source_url. Freshness: verified (boolean — pass true to mark the note re-confirmed as still true right now; only send this after the user has actually confirmed it), review_after (ISO 8601 datetime to time-box the note, or null to clear it). Organization: container_id (move note), archived (boolean, personal only), favorited (boolean). Tags: tag_list (full replace, comma-separated), add_tags, remove_tags. tag_list takes precedence over add_tags/remove_tags. Concurrent edit safety: pass expected_lock_version (the lock_version you saw when you last read the note via notes-get / notes-list / search) whenever you want a stale-write guard. If it doesn't match the current version, the update is rejected with the current state included so you can re-read and re-apply. Surgical edits (append_body / insert_after / insert_before / replace_find) are anchor-based and so don't need expected_lock_version for their body change — but if you also change title / summary / container_id alongside, those fields can still silently overwrite a newer save unless you supply expected_lock_version. Examples: insert under a heading {id: 42, append_to_section: 'Open Questions', section_body: '- Should we ship Friday?'}; replace a section {id: 42, replace_section: '## Status', section_body: 'Shipped 🎉'}; rename a heading {id: 42, rename_heading: 'TODO', new_heading: 'Done'}; tick a checklist item {id: 42, check_item: 'ship it'}; fix a typo {id: 42, replace_find: 'recieved', replace_with: 'received'}; safe full rewrite {id: 42, body: '...', expected_lock_version: 5}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Note ID (required) | |
| body | No | New body content — full replacement. Mutually exclusive with the other body-mutation modes. Pair with expected_lock_version for concurrent-edit safety. | |
| title | No | New title | |
| summary | No | New summary | |
| add_tags | No | Comma-separated tags to add to existing tags (ignored if tag_list is provided) | |
| archived | No | Archive (true) or unarchive (false) the note. Personal notes only. | |
| tag_list | No | Full replacement comma-separated tag list (takes precedence over add_tags/remove_tags) | |
| verified | No | Pass true to mark the note re-confirmed as still true as of now (the 'mark verified' affordance). Refreshes verified_at and clears 'stale' status. Only send after the user has confirmed the note is still accurate. | |
| favorited | No | Favorite (true) or unfavorite (false) the note. Personal and team notes. | |
| check_item | No | Text of a checklist item to tick (set to '[x]'). Matched case- and whitespace-insensitively; a leading bullet/checkbox in the text is ignored. Must match exactly one item. | |
| source_url | No | New source URL | |
| append_body | No | Content to append to the existing body. Mutually exclusive with the other body-mutation modes. | |
| insert_body | No | Text to insert. Must be paired with either insert_after or insert_before. Mutually exclusive with the other body-mutation modes. | |
| new_heading | No | New heading text for rename_heading. The original level is preserved unless this carries its own leading '#' markers. | |
| remove_tags | No | Comma-separated tags to remove from existing tags (ignored if tag_list is provided) | |
| container_id | No | Folder (container) id to move the note into; pass null to move it to the inbox (remove it from its folder) | |
| insert_after | No | Anchor snippet from the existing body — insert_body is inserted immediately after the unique occurrence. Anchor must match exactly once; include surrounding context to disambiguate. | |
| replace_find | No | Snippet to find in the existing body. Must match exactly once. Mutually exclusive with the other body-mutation modes. | |
| replace_with | No | Optional replacement for replace_find. Omit it (or pass an empty string) to delete the matched snippet. | |
| review_after | No | ISO 8601 datetime after which the note should be treated as stale (time-boxing), or null to clear it. | |
| section_body | No | The content for replace_section / append_to_section. Required when either is given. | |
| uncheck_item | No | Text of a checklist item to untick (set to '[ ]'). Same matching rules as check_item. | |
| insert_before | No | Anchor snippet from the existing body — insert_body is inserted immediately before the unique occurrence. Anchor must match exactly once. | |
| rename_heading | No | Heading to rename (with or without leading '#'). Pair with new_heading. Heading must match exactly one. | |
| replace_section | No | Heading whose section content should be replaced (with or without leading '#', e.g. '## Status' or 'Status'). Replaces everything under the heading up to the next same-or-higher-level heading, keeping the heading line. Pair with section_body. Heading must match exactly one. | |
| append_to_section | No | Heading to append content to (with or without leading '#'). Adds section_body at the END of that section — the safe way to 'insert under a heading'. Pair with section_body. Heading must match exactly one. | |
| expected_lock_version | No | Optional concurrent-edit guard. Pass the lock_version you saw when you last read the note; if it doesn't match the current version, the update is rejected and you should re-read and re-apply. Checked whenever supplied — covers title, summary, container_id, body, anything else. Surgical body edits without this param still work and remain anchor-safe; supply it any time you want a stale-write guard for the other fields too. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: explains concurrent edit safety, anchor-based surgical edits, destructive behavior (delete via replace_find), precedence rules (tag_list over add_tags), and field-specific constraints (archived personal only, favorited personal/team). 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 long but well-structured, starting with a clear purpose and then detailing operations. It includes examples and uses paragraph breaks for readability. While slightly verbose, every sentence adds value given the 27 parameters. The front-loading of the core purpose is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all operations, parameters, concurrency, and examples comprehensively. However, it does not mention the return value or error handling beyond the lock version rejection. Given no output schema, this is a minor gap but overall very complete.
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?
With 100% schema coverage, the description goes beyond baseline by providing examples for each body-mutation mode, clarifying mutual exclusivity, explaining anchor matching rules, and detailing expected_lock_version usage. It adds value that the schema alone does not.
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 a note and lists specific operations: edit content, move folders, archive/favorite, change tags. It distinguishes from siblings by explicitly stating it is the tool for moving notes between folders, with no separate move tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive guidance on when to use different parameter combinations and the expected_lock_version for concurrency. It gives examples and clarifies surgical edits vs full rewrites. However, it does not explicitly state when not to use (e.g., prefer notes-create for new notes), though it is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchARead-onlyIdempotentInspect
Search across notes, containers, and tags in one call. Returns results grouped by type with pagination metadata (total_count, page, per_page, total_pages). Required: query (string). Optional: types (array, default all three), search_scope ('all'|'personal'|'team:'), scope ('active'|'archived'), container_id (integer, ignored when search_scope is 'all'), tags (array, AND logic), tag_ids (array, AND logic), include_nested (boolean), include_body (boolean, default false — when true each note includes its full body), created_after / created_before / updated_after / updated_before (ISO 8601 datetime filters on note timestamps), page (integer, default 1), per_page (integer, default 25, max 100). Note results include a snippet of the matching portion.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for note results (default: 1) | |
| tags | No | Filter note results to notes with ALL these tags (by name) | |
| query | Yes | Search query string (required) | |
| scope | No | Search active or archived notes (default: active) | |
| types | No | Which types to search. Defaults to all three: ['notes', 'containers', 'tags'] | |
| tag_ids | No | Filter note results to notes with ALL these tags (by ID) | |
| per_page | No | Results per page for notes, max 100 (default: 25) | |
| container_id | No | Filter note results to this container (ignored when search_scope is 'all') | |
| include_body | No | Include the full note body on each note result (default: false) | |
| search_scope | No | Search scope: 'all' (default, personal + all teams), 'personal' (personal notes only), or 'team:<id>' (specific team). Applies to note results. | |
| created_after | No | Filter notes created on or after this ISO 8601 datetime (e.g. '2026-04-01T00:00:00Z') | |
| updated_after | No | Filter notes updated on or after this ISO 8601 datetime | |
| created_before | No | Filter notes created before this ISO 8601 datetime | |
| include_nested | No | Include notes from sub-containers when container_id is set (default: false) | |
| updated_before | No | Filter notes updated before this ISO 8601 datetime |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: parameter defaults, interaction between container_id and search_scope, include_body effect, and note snippet inclusion. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently covers all key aspects: purpose, return structure, and all parameters with defaults and behavior. While slightly long, every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (15 parameters, no output schema), the description provides comprehensive information: all parameters, their defaults, constraints, and return structure (grouped by type, pagination metadata, snippet). No critical gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters with descriptions (100% coverage). The description adds semantic value beyond the schema by explaining default values, logical relationships (e.g., container_id ignored when search_scope is 'all'), and parameter behavior (e.g., tags use AND logic).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search across notes, containers, and tags in one call.' It differentiates from sibling tools by emphasizing cross-type search and includes specific output details like results grouped by type with pagination metadata.
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 cross-type searches but does not explicitly state when to use this tool versus alternatives like notes-list, containers-list, or tags-list. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tags-createAInspect
Create a new tag. Check tags-list first to avoid duplicates. Required: name (string). Tag names are automatically lowercased.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Tag name (required) |
Tool Definition Quality
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.
tags-listARead-onlyIdempotentInspect
List all tags with their notes_count. Paginated. Optional: page (integer), per_page (integer).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| per_page | No | Results per page |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds beyond annotations: specifies paginated and includes notes_count. No contradictions with readOnlyHint and idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no fluff, key info front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a list tool; no output schema but mentions notes_count. Could note default pagination values but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, each parameter described in schema. Description only repeats parameter types, not adding meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists all tags with notes_count and is paginated. Distinguishes from sibling tools like tags-create and tags-manage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for listing tags, but no explicit when-to-use or alternatives. Adequate for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tags-manageADestructiveInspect
Rename, merge, or delete a tag — the cleanup tools for the tag list (this operates on the tag itself, unlike notes-update which only edits one note's tags). Required: action ('rename'|'merge'|'delete') and the tag to act on via name (string, case-insensitive) or tag_id (integer). For 'rename' also pass new_name. For 'merge' also pass the destination via target_name or target_id: every note on the source tag is moved onto the destination and the source tag is deleted — ideal for collapsing duplicates like 'machine learning' into 'machine-learning'. If target_name names a tag that doesn't exist yet, it's created, so you can merge straight into a clean canonical name without creating it first. 'delete' removes the tag from all its notes and deletes it; deleting a name that doesn't exist succeeds as a no-op (already_absent: true), so it's safe to retry. Merge and delete are destructive and cannot be undone; check tags-list first.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the tag to act on (case-insensitive). Provide this or tag_id. | |
| action | Yes | Action: 'rename', 'merge', or 'delete' (required) | |
| tag_id | No | ID of the tag to act on. Provide this or name. | |
| new_name | No | New name for the tag (required for action 'rename'). | |
| target_id | No | ID of the destination tag to merge into (for action 'merge'). Provide this or target_name. | |
| target_name | No | Name of the destination tag to merge into (for action 'merge'). Provide this or target_id. |
Tool Definition Quality
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.
teams-getARead-onlyIdempotentInspect
Get team details including the 10 most recent notes. Required: id (integer).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Team ID (required) |
Tool Definition Quality
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.
teams-listARead-onlyIdempotentInspect
List all teams the user is a member of, including members_count, notes_count, and containers_count for each team. No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
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.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!