hjarni

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

Annotations already establish this is a non-destructive write operation. The description adds the domain context (note organization) but does not disclose additional behavioral traits like nesting constraints, uniqueness requirements, or success responses.

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 with zero waste. The parenthetical '(folder)' efficiently clarifies the container concept, and 'organizing notes' immediately establishes domain relevance without verbosity.

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?

Appropriate for the tool's complexity (simple create with 3 params, no output schema). Leverages complete annotations and schema effectively, though it could explicitly mention hierarchical capabilities implied by the parent_id parameter.

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 description coverage, the schema adequately documents all parameters. The description adds the conceptual metaphor ('folder') which supports understanding the parent_id nesting parameter, but does not add syntax or constraint details 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 specific action ('Create'), resource ('container (folder)'), and domain context ('for organizing notes'), effectively distinguishing it from sibling tools like containers-update or notes-create.

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

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

Provides clear domain context ('organizing notes') that helps identify when to use this tool versus content creation tools, though it lacks explicit contrasts with containers-update (modification) or specific prerequisites.

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

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

With annotations already declaring readOnlyHint=true, the description adds valuable behavioral context: it discloses that LLM instructions are included only 'if set' (conditional presence) and clarifies that include_tree returns 'ancestors and children' (structural relationships). 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?

Two sentences with zero waste: the first establishes purpose and key data fields, the second provides parameter guidance. Information is front-loaded with the core action, and every word earns its place.

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

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

Given the tool's simplicity (single resource retrieval), 100% schema coverage, and read-only annotations, the description adequately covers what is returned (container, LLM instructions, optional tree). It appropriately omits error handling details given the lack of output schema, though mentioning 'not found' behavior would elevate this to a 5.

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

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

Despite 100% schema description coverage (baseline 3), the description adds semantic value by explaining the functional purpose of include_tree ('to also get ancestors and children') rather than just restating the schema's technical description. This helps the agent understand the data structure implications.

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

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

The description clearly states the specific action (Get), resource (single container), and identification method (by ID). It distinguishes from siblings containers-list (plural/enumeration), containers-create (write), and containers-update (mutation) through the singular 'get' verb and ID-based targeting.

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 optional include_tree parameter ('to also get ancestors and children'). However, it lacks explicit guidance on when to choose this tool versus containers-list (e.g., 'use this when you have a container ID; use containers-list to browse').

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

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

Annotations confirm read-only safety. Description adds valuable behavioral context about default scoping (root-level only) and the personal/team context switch that isn't captured in annotations. Could add more about pagination or rate limits, but covers primary behavioral axes.

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, zero waste. First sentence establishes purpose; second sentence delivers critical default behavior and parameter guidance. Every word earns its place.

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

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

Appropriate for a list tool with 4 parameters and safety annotations. Covers primary filtering behaviors (roots vs team). Lacks explicit mention of pagination behavior or return structure, but schema covers parameter details adequately for an agent to proceed.

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, baseline is 3. Description adds semantic context by linking team_id to the personal-vs-team behavioral shift and reinforcing the default state when parameters are omitted. Elevates understanding 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?

States specific action (List) and resource (containers/folders) with context (organizing notes). Clarifies personal vs team scope which implicitly distinguishes from sibling operations, though it doesn't explicitly contrast with containers-get for single-item 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?

Provides clear guidance on default behavior (root-level personal containers) and when to use team_id parameter (for team containers). Lacks explicit 'when not to use' or direct sibling comparisons, but effectively guides the primary use case selection.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false. The description adds the specific mutable fields/behaviors beyond the generic 'update' label, but does not disclose behavioral details like partial update semantics (only 'id' is required), validation rules, or side effects of reparenting (e.g., circular reference handling).

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, front-loaded with the core action. The parenthetical list efficiently maps to the optional parameters without redundancy. Zero 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?

Given 100% schema coverage and present annotations, the description adequately covers the tool's purpose for a 5-parameter mutation operation. However, it could improve by noting the partial update capability (since only 'id' is required) or referencing error conditions.

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 description coverage, the baseline is 3. The description maps parenthetical operations to parameters (rename→name, move parent→parent_id, etc.) but adds no semantic meaning beyond what the schema already provides (e.g., no constraints on name length or position integer limits).

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

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

States specific verb 'Update' and resource 'container'. The parenthetical enumeration of operations (rename, change description, move parent, set position) clearly distinguishes this from sibling tools like containers-create or containers-get, and clarifies the scope of modifications possible.

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 context by specifying 'existing container', which distinguishes it from containers-create. However, it lacks explicit when-to-use guidance (e.g., 'use this for partial modifications, not for creating new containers') or prerequisites (e.g., 'requires container ID from containers-list').

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

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

Annotations already confirm readOnlyHint=true and destructiveHint=false. The description adds value by disclosing what specific data points are returned (counts vs recent items), but does not address caching behavior, performance characteristics, or data freshness.

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 structure with zero redundancy. The colon effectively separates the high-level action from the specific data details. Every word earns its place; no filler 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 parameter-less read-only tool, the description adequately covers the return value semantics by listing the specific metrics included (counts and recent notes). While an output schema would be ideal, the textual description provides sufficient context for an agent to understand what data structure to expect.

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 zero parameters and 100% schema coverage (empty object), the baseline score applies. The description does not need to explain input parameters, but helpfully enumerates the output data categories (counts, recent notes) which aids in understanding the tool's utility despite having no inputs.

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

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

The description uses specific verbs ('Get an overview') and enumerates exact resources retrieved (counts of notes, containers, tags, inbox items, recent notes). It clearly distinguishes this aggregate dashboard view from sibling CRUD tools like notes-list or containers-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?

While the description implies usage through the term 'overview' and listing aggregate metrics, it lacks explicit guidance on when to prefer this over specific entity retrieval tools (e.g., notes-list). No 'when-not-to-use' or alternative recommendations are provided.

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

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

Annotations declare readOnlyHint=false (write operation) and destructiveHint=false. The description adds the critical behavioral detail that data must be base64-encoded, which is essential for correct invocation. However, it omits other behavioral aspects like error handling, size limits, or return values.

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

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

Extremely efficient at two sentences. The first establishes the operation, the second specifies the encoding format—both essential. No redundant or filler 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?

Adequate for the input side given complete schema coverage and annotations. However, no output schema exists, and the description fails to indicate what the tool returns (e.g., attachment ID, success boolean), leaving a gap in the contract.

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 all parameters fully documented (e.g., 'Base64-encoded file contents' for the data field). The description reinforces the base64 requirement but does not add semantic meaning beyond what the schema already provides, meriting the baseline score.

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

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

States specific action ('Attach'), resource ('file'), and target ('note'). The mention of 'base64-encoded string' implicitly distinguishes this from the sibling 'files-attach_from_url', clarifying this is for direct content 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?

Provides clear context for when to use this tool (when file contents are available as base64 data) versus URL-based alternatives. While it doesn't explicitly name the sibling alternative, the encoding requirement provides strong implicit guidance on tool selection.

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

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

Adds valuable behavioral detail 'Follows one redirect' which is critical for network operations and not present in annotations. Annotations already cover safety profile (readOnly=false, destructive=false), so the description successfully augments with execution specifics.

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

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

Two sentences with zero waste. Main action is front-loaded, followed by specific behavioral constraint. Every word earns its place.

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

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

Given complete schema and annotations, description adequately covers the core operation and redirect behavior. Minor gap: lacks error handling context (what happens if URL is unreachable or note ID invalid), 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 has 100% description coverage, so parameters are fully documented in structured fields. Description does not add semantic nuances beyond the schema (e.g., no examples or format details for URL), warranting baseline score.

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 the specific action (fetch from URL + attach to note) and distinguishes from sibling 'files-attach' by explicitly mentioning the URL source. Verb and resource are precise.

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 scenario through 'from a URL' but lacks explicit guidance on when to use this versus siblings like 'files-attach' (likely for existing files) or 'files-create_upload_url'. No exclusion criteria provided.

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

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

Annotations declare readOnlyHint=true (safe read operation). Description adds valuable behavioral context by enumerating the three specific status values ('pending', 'completed', 'expired') and explaining what each state means in the upload lifecycle, which is not inferable from annotations alone.

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

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

Two well-structured sentences with zero waste: first establishes purpose and sibling relationship, second documents return values (compensating for missing output schema). Information is front-loaded and dense.

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

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

For a single-parameter status-check tool with no output schema, the description is complete. It documents the three possible return states and their meanings, providing sufficient information for an agent to interpret results without requiring an output schema.

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

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

Input schema has 100% description coverage for the 'token' parameter ('Upload token from files-create_upload_url response'). Description does not add parameter-specific semantics beyond what the schema already provides, which is acceptable given full schema coverage.

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

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

Description uses specific verb 'Check' with resource 'status of a file upload link' and explicitly scopes it to links 'created by files-create_upload_url', clearly distinguishing it from sibling tools like files-create_upload_url or files-attach.

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?

Establishes clear workflow relationship by referencing the sibling tool files-create_upload_url, indicating this is the second step in a two-step upload process. Lacks explicit 'when not to use' guidance, but the dependency implication is clear.

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

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

Despite annotations indicating readOnlyHint=false (implying state change), the description adds critical behavioral context not present in structured fields: the URL is 'one-time,' it 'bypasses the conversation,' and has a specific '30 minutes' TTL. These operational details are essential for correct invocation.

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 efficiently cover: (1) core function, (2) user workflow/value prop, (3) time constraint, and (4) companion tool. No redundancy; front-loaded with essential action; every sentence earns its place.

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

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

Given the lack of output schema, the description adequately explains the return value's purpose (URL for user upload) and lifecycle (30-min expiry). However, it could briefly characterize the return structure (e.g., 'returns a URL string') for full completeness.

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

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

With 100% schema description coverage, the baseline is 3. The description mentions 'attaching a file to a note' which aligns with the 'note_id' parameter, but adds no additional semantic detail (format constraints, example values) beyond what the schema already provides.

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

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

The description opens with a specific verb ('Generate') and resource ('one-time upload URL'), clearly defining the tool's function. It distinguishes itself from sibling tools like 'files-attach' by emphasizing this is for direct user upload bypassing the conversation, and explicitly references 'files-check_upload' for verification workflow.

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 workflow guidance ('Share this URL with the user'), explains the benefit ('saving tokens'), notes the temporal constraint ('expires after 30 minutes'), and names a specific sibling tool ('Use files-check_upload') for the next step. This creates a complete decision tree for the agent.

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

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

Annotations indicate readOnlyHint=true, confirming the safe read-only nature. The description adds crucial behavioral context not present in annotations: the URL is temporary and expires after a few minutes. This discloses an important operational constraint (time-limited validity) that affects how the agent must handle the response.

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 well-structured sentences: first states purpose, second provides usage instruction, third states operational constraints. Every sentence earns its place with zero redundancy. Information is front-loaded with the 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 two-parameter tool without an output schema, the description adequately explains what the tool returns (a URL), how to use the result (share with user), and critical behavioral constraints (temporary/expiring). Given the low complexity and absence of output schema, no additional context is required.

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 description coverage ('Note ID' and 'File ID (from notes-get response)'), the schema fully documents parameters. The description references 'a file attached to a note' which aligns with the parameters but adds no additional semantic detail about the parameters themselves beyond what the schema provides, meeting the baseline for high-coverage schemas.

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 specific action (get a temporary download URL) and resource (file attached to a note), using clear verbs. It effectively distinguishes from sibling tools like files-attach or files-create_upload_url by specifying this generates a download (not upload) URL for existing attachments.

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 usage guidance by instructing to 'Share the URL with the user so they can download the file in their browser' and warns that 'The URL expires after a few minutes.' While it lacks explicit 'when not to use' statements comparing against all file-related siblings, the expiration constraint provides actionable temporal guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, establishing the safety profile. The description confirms the destructive nature with 'Remove' but fails to clarify scope: whether the file is permanently deleted from storage or merely detached from the note. No additional behavioral traits (auth, rate limits, side effects) are disclosed.

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 of 7 words with zero redundancy. Information is front-loaded and immediately actionable. The brevity is appropriate for the tool's simplicity.

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 simple two-parameter operation, complete schema coverage, and presence of safety annotations, the description is nearly sufficient. Minor gap: does not clarify whether the operation deletes the file entirely or just removes the attachment reference, which would be helpful for an agent determining data integrity implications.

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%, with parameters fully documented (including the helpful hint that file_id comes from notes-get response). The description reinforces the relationship between parameters ('file attachment from a note') but does not add semantic meaning beyond what the schema already provides. 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 uses specific verb 'Remove' with clear resource 'file attachment' and context 'from a note'. It effectively distinguishes from sibling tools like files-attach (which adds files) and notes-delete (which would delete the entire note).

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

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

The description implies usage through the action verb, but provides no explicit guidance on when to use this versus alternatives (e.g., 'use files-attach to add files') or prerequisites (e.g., 'use notes-get to retrieve file_id').

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

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

Adds crucial behavioral context beyond annotations: specifies that 'container' level 'includes inheritance chain' (revealing aggregation behavior) and provides timing guidance for 'brain' level. Consistent with readOnlyHint=true annotation.

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, perfectly front-loaded: first states purpose, second maps levels to use cases. No redundancy. Parenthetical details ('call early', 'includes inheritance chain') efficiently convey critical behavioral constraints without verbosity.

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 simple read-only operation with complete schema coverage and clear annotations, the description adequately covers all necessary context: purpose, level semantics, inheritance behavior, and usage timing. No output schema exists but return value is self-evident from 'Get' verb.

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, adds semantic meaning to enum values (e.g., explaining 'brain' means 'global instructions', 'container' involves inheritance) and contextualizes when 'id' parameter is needed through the level 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 uses specific verb 'Get' with resource 'LLM instructions' and scope 'at the specified level'. Clearly distinguishes from sibling 'instructions-update' by being read-only, and differentiates from 'containers-get'/'teams-get' by focusing on instruction retrieval rather than entity 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?

Provides explicit mapping for each level value ('brain' for global/call early, 'personal_root' for personal space, etc.) and temporal guidance ('call early in conversations'). Implicitly contrasts with update operations but does not explicitly name alternatives.

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

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

Annotations already declare this is a write operation (readOnlyHint: false) and non-destructive (destructiveHint: false). The description adds semantic context for the level parameter but does not disclose behavioral details like the replacement mechanism (described in schema) or immediate effects of the update.

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

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

Two sentences with zero waste: first establishes the core operation, second provides the essential enum mapping. Information is front-loaded and appropriately sized for the tool's complexity.

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

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

Given the simple 3-parameter schema with full coverage and present annotations, the description is sufficient for invocation. It could be improved by noting that 'id' is conditionally required or referencing the 'instructions-get' sibling for read operations, but the core functionality is adequately covered.

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, the description adds significant value by explaining what each enum value for 'level' actually represents (e.g., 'brain' means global), which the schema only lists without semantic definitions. It compensates for the schema's lack of conceptual explanation for the level options.

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

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

The description clearly states the specific action (Update) and resource (LLM instructions) with scope (at the specified level). It effectively distinguishes from sibling 'instructions-get' by stating the update operation and level-specific scoping.

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 crucial mapping of enum values to their semantic meaning ('brain' = global, 'personal_root' = personal space, etc.), which guides correct level selection. However, it lacks explicit guidance on when to use this versus 'instructions-get' or prerequisites like when 'id' is required.

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

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

The description adds valuable behavioral context by specifying the link is 'bidirectional'—a critical detail not present in parameter annotations or the schema fields. It aligns correctly with destructiveHint=true (for removal) and readOnlyHint=false without contradiction.

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

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

The description is a single, efficient sentence of nine words with no redundancy. It is immediately front-loaded with the core action and resource, making it easy to parse.

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 100% schema coverage and presence of safety annotations, the description adequately covers the tool's purpose. However, it omits context about error conditions (e.g., linking non-existent notes) and return values that would be helpful for a destructive operation.

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

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

With 100% schema description coverage, the schema fully documents all three parameters (action enum, source/target IDs). The description adds no additional parameter semantics beyond the schema, meeting the baseline expectation.

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 creates or removes bidirectional links between notes, using specific verbs and identifying the resource. However, it does not explicitly differentiate from sibling tools like notes-update (which modifies content rather than relationships).

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

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

While the description mentions both 'create' and 'remove' actions, it provides no guidance on when to use this tool versus alternatives, nor does it state prerequisites such as whether the notes must exist beforehand or idempotency guarantees.

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

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

Annotations establish this is a non-destructive write operation. The description adds valuable behavioral context: the body supports Markdown, and specifically uses [[id:Note Title]] syntax for wiki-links. It also clarifies the team vs. personal workspace behavior not fully captured by annotations alone.

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

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

Three sentences, front-loaded with purpose. Every sentence adds value: sentence 1 defines the action, sentence 2 explains content format, sentence 3 explains workspace scoping. No redundancy or filler.

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

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

Given 7 parameters but 100% schema coverage and good annotations, the description adequately covers the primary usage patterns (markdown support, wiki-link syntax, team placement). It omits explicit mention of container_id, tag_list, and source_url, but these are well-documented in the schema.

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

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

With 100% schema description coverage, the baseline is 3. The description repeats the wiki-link format already present in the schema and adds minimal new semantic detail for the other 6 parameters (title, summary, tag_list, source_url, container_id).

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

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

The description opens with 'Create a new note,' providing a specific verb and resource. It implicitly distinguishes from sibling tools (notes-get, notes-list, notes-update, notes-delete) by specifying the 'create' action.

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

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

Provides clear context for the team_id parameter ('Use team_id to create in a team'), implying the default is personal space. However, it lacks explicit guidance on when to use this versus notes-update for existing notes, or how it relates to containers-create.

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

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

While the description aligns with annotations (destructiveHint: true) by stating 'permanently', it adds no other behavioral context beyond what annotations provide. It fails to disclose side effects (e.g., whether attached files are cascaded or orphaned), recovery options, or error conditions.

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 at only four words. Every word serves a purpose, with 'permanently' front-loaded to emphasize the destructive nature. No redundancy or filler content.

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

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

For a single-parameter destructive operation with complete schema coverage and clear annotations, the description is minimally sufficient. However, given the destructive nature, it could improve by mentioning output behavior (void vs. confirmation) or cascading effects.

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

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

With 100% schema description coverage, the single 'id' parameter is fully documented in the schema itself. The description adds no parameter-specific context, which is acceptable given the high schema coverage, meeting the baseline.

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

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

The description clearly states the action (delete) and resource (note) with the critical qualifier 'permanently' indicating irreversibility. However, it doesn't explicitly differentiate from sibling tools like files-remove, though the tool name makes the resource clear.

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 no guidance on when to use this tool versus alternatives (e.g., when to delete vs. update a note) or prerequisites (e.g., ownership requirements). It merely states what the tool does.

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

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

While annotations confirm this is read-only and non-destructive, the description adds valuable behavioral context about the return payload, specifying it includes 'full body content, tags, container, linked notes, and file attachments'. This compensates for the absence of an output schema by detailing what data richness to expect.

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 sentence that front-loads the core action and efficiently enumerates all included content types without redundant phrasing. Every clause serves to clarify the retrieval scope or return value composition.

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 (single required parameter, read-only operation) and comprehensive annotations, the description adequately explains the retrieval behavior and return value structure. The enumeration of returned fields provides sufficient completeness despite the lack of a formal output schema.

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

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

With 100% schema description coverage for the single 'id' parameter, the description reinforces the parameter's purpose by mentioning 'by ID' but does not add additional semantic details like ID format or discovery methods. This meets the baseline for high-coverage schemas.

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

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

The description uses the specific verb 'Get' with the resource 'note' and clarifies the scope 'single note by ID'. This effectively distinguishes it from sibling tools like notes-list (plural retrieval) and notes-create/notes-update (mutation operations).

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

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

The phrase 'by ID' clearly establishes that this tool requires a specific identifier, implicitly guiding users toward list or search tools for discovery first. However, it does not explicitly name these alternative tools or provide explicit 'when not to use' guidance.

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

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

Annotations indicate read-only safety (readOnlyHint=true), so the description adds valuable behavioral context by disclosing 'Returns paginated results'—critical information given the lack of an output schema. 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?

Front-loaded with purpose and critical behavior (pagination), followed by specific usage guidance. Four sentences with minimal redundancy. The repetitive 'Use X to...' structure is slightly mechanical but keeps the guidance scannable.

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

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

With 10 parameters and no output schema, the description covers pagination and major filtering mechanisms adequately but does not describe the return structure (what fields the notes objects contain). Sufficient for basic invocation but leaves output handling ambiguous.

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

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

While the schema has 100% coverage (baseline 3), the description adds meaningful usage context by grouping related parameters (linking container_id with include_nested, distinguishing tag/tags/tag_ids use cases) and clarifying their relationships beyond individual parameter 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?

States specific verb (List) and resource (notes) clearly, and mentions filtering/sorting capabilities. However, it does not explicitly differentiate from the sibling 'search' tool, which could cause confusion about when to use listing vs. searching.

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

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

Provides concrete usage patterns for key parameters (team_id for teams, container_id with include_nested for sub-containers, tag variants for filtering). However, it lacks explicit when-to-use/when-not-to-use guidance contrasting with siblings like 'notes-get' or 'search'.

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

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

Annotations already indicate this is a non-destructive write operation (readOnlyHint: false, destructiveHint: false). The description implies partial-update semantics (lists specific fields that 'can' be updated), but does not clarify error behavior, idempotency, or what happens if the note ID doesn't exist.

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 well-structured sentences with zero redundancy. The first establishes the core purpose; the second efficiently enumerates the specific update capabilities without filler.

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

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

Given the rich schema (9 parameters, 100% coverage) and safety annotations, the description covers the essential functionality. However, for a mutation tool, it lacks details on success/failure signals, partial update confirmation, or side effects.

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

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

Input schema has 100% description coverage, establishing a baseline of 3. The description maps prose concepts ('moving to a container', 'changing tags') to parameter names but does not add syntactic details, format constraints, or examples beyond what the schema already provides.

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

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

Clearly states the tool updates existing notes and enumerates specific capabilities (archiving, favoriting, container moves) that distinguish it from sibling tools like notes-create or notes-delete. However, it does not explicitly contrast with creation or deletion workflows.

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?

Lists capabilities but provides no explicit guidance on when to use this versus notes-create (e.g., 'use this to modify existing notes by ID, not to create new ones'), nor does it mention prerequisites like the note ID requirement.

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

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

Annotations confirm read-only safety. The description adds valuable behavioral context beyond annotations: it discloses that results are 'grouped by type,' mentions 'snippets' in results, and notes that container_id is ignored when search_scope is 'all' (by referencing them as filters). It does not contradict the readOnlyHint annotation.

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 efficiently cover: (1) core purpose, (2) return structure, (3) type filtering with example, and (4) full-text capabilities and filter categories. Information is front-loaded and 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?

Given 8 parameters and no output schema, the description adequately covers the search capabilities, filter interactions, and return grouping. It could be enhanced by briefly describing the result object structure or pagination behavior, but the mention of 'grouped by type' provides essential context for interpreting results.

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 description coverage, the baseline is 3. The description adds value by providing concrete syntax examples (e.g., 'types: ['notes'] for note-only search'), grouping related parameters conceptually ('all note filters'), and explaining the purpose of the scope parameter for archived search, enriching the 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 opens with 'Unified search across notes, containers, and tags,' providing a specific verb and resource. It distinguishes itself from sibling list tools (notes-list, containers-list, tags-list) by emphasizing 'unified' cross-resource search and 'full-text search with snippets,' clarifying this is for searching content rather than simple enumeration.

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 parameter-level guidance (e.g., 'Use the types parameter to search only specific types,' and noting archived search via scope). However, it lacks explicit comparison to sibling alternatives like notes-list or tags-list to indicate when to use the unified search versus specific list endpoints.

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

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

Annotations already establish this is a non-destructive write operation (readOnlyHint=false, destructiveHint=false). The description adds no behavioral context beyond this, failing to disclose return values (ID, full object?), idempotency, error conditions, or side effects of the creation.

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 brief at four words, containing no redundancy or filler. While appropriately concise for a single-parameter tool, it borders on under-specification and could benefit from one additional sentence regarding constraints or return values without sacrificing clarity.

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 low complexity (one required string parameter) and absence of an output schema, the description meets minimum viability by identifying the core action. However, it omits return value documentation and uniqueness constraints that would be necessary for a complete agent understanding.

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 description coverage, the input schema fully documents the 'name' parameter. The description makes no mention of parameters, but since the schema is complete, it meets the baseline expectation without adding supplementary semantic context.

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

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

The description states a clear verb (create) and resource (tag), making the basic purpose unambiguous. However, it lacks specificity about what kind of tag is being created (e.g., for files, notes, or containers) and does not differentiate from sibling operations like tags-list beyond the obvious CRUD distinction.

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 no guidance on when to use this tool versus alternatives, prerequisites for creation (e.g., uniqueness constraints, permissions), or what happens if a tag with the same name already exists. No 'when-not' scenarios or workflow context is provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing this is a safe read operation. The description adds no behavioral context about pagination defaults, total result limits, or what 'tags' represent in this system's domain (files, notes, etc.).

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 three-word description is maximally efficient with zero redundancy. However, it borders on underspecification given the lack of output schema and unclear relationship to the broader tag system.

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 list operation with full schema coverage, the description meets minimum viability but lacks context about return value structure (no output schema exists) or how tags relate to other entities (notes, files) in the sibling set.

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 description coverage for the 'page' and 'per_page' parameters, the schema carries the semantic burden. The description doesn't add usage guidance for these pagination parameters (e.g., default behavior when omitted), warranting the baseline score.

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 (tags), making the tool's function immediately apparent. While it doesn't explicitly differentiate from sibling 'tags-create', the distinction is implicit in the action verb.

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 no guidance on when to use this tool versus alternatives like 'search' or how to handle pagination. It doesn't indicate whether clients should paginate through all results or if there are limits.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds valuable context that 'recent notes' are included in the response, which is not evident from annotations. However, it omits details about how many notes constitute 'recent' or what other 'details' are returned.

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, efficient sentence that front-loads the action verb. There is no redundant or filler text; every word contributes to understanding the tool's function.

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 (single required parameter, read-only operation, no output schema), the description adequately covers the essential behavior. It specifies the inclusion of recent notes, providing sufficient context for an agent to understand what data is retrieved without needing to detail the response structure.

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 description coverage (the 'id' parameter is fully documented as 'Team ID' in the schema), the baseline is 3. The description adds no additional semantic meaning for the parameter (e.g., where to obtain the ID, format specifics) beyond what the schema already provides.

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

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

The description states a specific action ('Get') and resource ('team details'), and adds scope via 'including recent notes.' However, it does not explicitly differentiate from sibling 'teams-list' (collection vs. single resource retrieval), though the singular/plural naming provides implicit distinction.

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 no guidance on when to use this tool versus alternatives. It does not clarify whether to use 'teams-list' when searching for a team without an ID, or whether 'notes-list' is preferred when only notes are needed rather than full team details.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable scope constraint ('user is a member of') defining the result set, but does not disclose pagination behavior, rate limits, or return structure.

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, front-loaded with the action and scope. No redundant words; the phrase 'the user is a member of' is essential for defining the result set boundary.

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

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

For a simple read-only list operation with good annotations coverage and no parameters, the description is sufficient. Minor gap: no output schema exists and description does not characterize the return format (e.g., list of IDs vs full objects).

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?

Tool accepts zero parameters with 100% schema coverage. Per calibration guidelines, 0 parameters establishes a baseline of 4; the description correctly implies no configuration is needed by omitting parameter discussion.

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 provides specific verb ('List'), resource ('teams'), and scope constraint ('the user is a member of'), clearly distinguishing it from sibling 'teams-get' which likely 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?

Description implies usage context by specifying 'all teams,' suggesting it is for enumeration rather than specific retrieval, but does not explicitly contrast with 'teams-get' or state when to prefer one over the other.

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