UseMyContext

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

Annotations already show readOnlyHint=true and destructiveHint=false. Description adds 'READ-ONLY: you cannot change the plan', and explains billing changes happen at usemycontext.ai. Provides valuable behavioral 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?

The description is a single concise paragraph covering purpose, usage, limitations, and read-only nature. It is front-loaded with the main action. Could be slightly more structured with bullet points but is efficient.

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

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

No parameters, annotations present, output schema exists (so return values are documented). Description is complete: specifies what is reported, what is excluded, and where to manage plans. Covers all necessary context for an agent.

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 (0), so baseline 4 applies. Description does not need to add parameter details as there are none.

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 reports the user's current plan and usage details (tier, projects, storage, limits, subscription, management location). It distinguishes itself from sibling tools by focusing on plan/usage metadata, not files, facts, or profile content.

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: when user asks about plan, storage/project usage, or nearing limits. Implicitly excludes file/profile queries via 'Metadata only' and 'read-only'. Does not list alternatives 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.

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

Annotations already declare readOnlyHint and destructiveHint. The description adds that it returns actual text with citations, the agent does the reasoning, and it is always allowed. This provides useful behavioral transparency beyond the annotations.

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

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

The description is two sentences with no wasted words. The first sentence front-loads the main purpose and output, making it efficient and 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 presence of an output schema, the description adequately covers all essential aspects: semantic search, passage citation, read-only nature, and usage context. It 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?

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond what the schema already provides for parameters like query, k, handle, and projectId.

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 searches documents by meaning, returns relevant passages with source citations, and contrasts with other tools like search or search_files by specifying it returns actual text, not file links or pre-written answers.

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

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

The description explicitly says to use this tool to answer questions from the user's documents, and contrasts what it does not do (file link, filename list, pre-written answer). It also mentions it is always allowed and read-only. However, it does not explicitly differentiate from all sibling tools like shared_context.

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

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

Annotations already include readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it states the tool is read-only, audited, and that large files are truncated. It also notes that permissions and audit are the same as get_file, fully leveraging the annotations while adding critical details.

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

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

The description is well-structured and front-loaded with the core purpose. It is slightly lengthy due to thorough comparisons and edge-case explanations, but every sentence adds value. A perfect 5 would be more succinct while retaining 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 complexity (3 params, 100% schema coverage, output schema present, and annotations), the description is remarkably complete. It covers the tool's behavior, limitations (truncation), relationship to sibling, and usage context. No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful nuance beyond the schema: it explains the handle parameter's behavior (honored only for account-wide connections, precedence over projectId) and the conditionality of projectId. This extra context justifies a score of 4.

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

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

The description clearly states the tool fetches one document's full extracted text by id, specifically for the deep-research result shape. It distinguishes itself from the sibling get_file by noting it is the same read but with a different output contract, 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 provides explicit guidance on when to use this tool vs. the alternative: use fetch when the client requires the id/title/text/url fetch contract (ChatGPT deep research); otherwise prefer get_file. It also notes the alias relationship, giving clear context for 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?

Discloses truncation for large files, download links for binary files, and auditing. Adds meaningful context beyond annotations (readOnlyHint, destructiveHint), with 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 core purpose, no wasted words. Each sentence adds distinct 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?

Covers return types, truncation, binary file handling, and auditing. Given output schema exists and annotations are rich, description is fully complete for this tool.

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

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

Schema coverage is 100%, so description does not need to add much. It only briefly mentions fileId usage without additional syntax or format details. Adequate but not enriching.

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 gets full text content of a file by ID, distinguishes from sibling 'ask_docs' for targeted passages. Also specifies behavior for binary files and audits.

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 tells when to use (get full content) vs ask_docs (targeted passages), notes truncation for large files, and mentions auditing. Provides clear context for 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 declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by listing specific read-only behaviors (cannot create/delete profiles, manage billing, etc.) and stating 'Returns static public information only.' 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 front-loaded with the core purpose, then provides detailed usage guidance and limitations. It is efficient for the complexity, though slightly long due to the list of cannot-dos.

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, rich annotations, and an output schema (implied), the description covers all necessary aspects: what the tool does, when to use it, its limitations, and what it returns. 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?

The tool has zero parameters and schema coverage is 100%, so per guidelines baseline is 4. The description adds value by describing what the tool returns (static public info, no user data) rather than needing to explain parameters.

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

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

The description starts with 'Explain what UseMyContext is...' providing a specific verb and resource. It clearly distinguishes this info tool from sibling tools like account or fetch by describing its scope (service overview, capabilities, settings).

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

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

The description explicitly lists when to call ('user asks what UseMyContext is, what you can do, where to find pricing...') and includes a detailed 'IMPORTANT' section with what the tool cannot do, directing users to external links.

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 behavioral context beyond readOnlyHint: explains metadata-only listing and status field implications (queueEtaSeconds for ask_docs). 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?

Short, front-loaded, every sentence adds value. 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?

Output schema exists so return values not needed. Covers status field and implications well. Could mention pagination or limits but fine for a list 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% so parameters are already documented. Description adds no parameter-specific value beyond 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?

Clearly states it lists user's files with metadata only. Differentiates from get_file and search_files by specifying scope and 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?

States 'Always allowed' and explains status field relevance to ask_docs. Lacks explicit when-not-to-use or alternatives, 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.

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

The description adds context beyond annotations by stating 'Always allowed; read-only.' and detailing the exact return fields. Annotations already indicate readOnlyHint=true, so no contradiction. The description effectively communicates the tool's safety and non-destructive nature.

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 and well-structured: it opens with the core purpose, lists return fields, provides usage guidance, notes what is excluded, and ends with a safety assurance. 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 has no parameters and an output schema exists, the description covers all necessary context: purpose, return values, usage scenarios, and constraints. It is complete for an agent to understand when and how to use it.

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?

There are no parameters, so the baseline is 4 per guidelines. The description does not need to add parameter info, and the schema coverage is 100%.

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 lists the user's own profiles (their projects) and specifies the exact metadata returned (name, handle, privacy status, default connection). It distinguishes from siblings like 'profile' by focusing on listing multiple profiles.

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

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

Explicit usage guidance is provided: 'Use this when the user asks how many profiles they have, what their profiles are called, or which profile you are connected to.' It also clarifies what the tool does not do (no file content, no facts, no compiled context).

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by stating no file content, that it reports privacy status, and details parameter handling (e.g., handle refused for non-own profiles).

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

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

The description is two sentences but quite dense with information. While every sentence adds value, it could be slightly more concise. However, structure is good with main action first.

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 presence of an output schema, the description doesn't need to detail return values. It covers parameter behavior thoroughly, mentions privacy status, and addresses edge cases like single-project connections. 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 coverage is 100%, but the description significantly enriches understanding: explains that handle is an alternative to projectId, takes precedence, refused if not user's own, and that both are ignored for single-project connections.

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: returning the user's compiled personal context synthesized from accepted facts. It distinguishes from sibling tools like shared_context for reading shared context, and mentions no file content.

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

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

Explicit guidance: 'Always allowed.' Differentiates when to use handle vs projectId, notes that handle takes precedence and is only for account-wide connections, and directs to shared_context for others' context.

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

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

Annotations already indicate readOnlyHint=true, and the description confirms 'Read-only; always allowed.' Adds crucial behavior details: exact row execution, handling of non-numeric cells for numeric ops (skippedNonNumeric counted), and error response listing real columns.

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?

Every sentence earns its place: purpose, guidelines, parameter details, examples, error handling, and read-only assurance. Front-loaded with the main action and key constraint. No 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?

Given the tool's complexity (4 params, nested query object) and presence of output schema, the description is fully adequate: covers usage scenarios, parameter semantics with examples, error recovery, and behavioral traits. Leaves no significant gap.

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

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

Schema coverage is 100%, but the description adds extensive meaning beyond schema by fully documenting the query grammar, providing multiple JSON examples, and explaining how column names match case-insensitively. The description compensates for the nested schema complexity.

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 specifies a clear verb ('Run an EXACT, deterministic query'), a specific resource ('ONE tabular file'), and distinguishes itself from siblings like ask_docs and get_file by stating what it does differently (exact vs semantic, tabular vs prose).

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 tells when to use this tool (counting, summing, averaging, filtering, exact lookups) and when to use alternatives (ask_docs for prose, get_file for whole document). Includes examples of questions that warrant its use.

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

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

Beyond annotations (readOnlyHint true), the description adds behavioral context: same data/permissions as search_files, the specific result shape, and 'Read-only; always allowed.' No contradictions; it enriches transparency.

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 despite containing multiple pieces of critical information. It front-loads the primary function, then covers alias, usage guidance, and result usage in a logical flow with no superfluous 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?

The description covers alias relationship, permission model, result shape, parameter nuances, and post-search actions. Given the presence of an output schema, it fully equips the agent to select and 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?

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds value beyond schema by explaining that handle and projectId are honored only for account-wide connections, and handle takes precedence over projectId. This enriches semantic understanding.

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

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

The description clearly states the tool searches files by filename and returns results in a 'deep-research result shape'. It distinguishes from sibling search_files by noting they are the same search but with different output contracts, making the purpose specific and unambiguous.

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

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

Explicitly advises when to use this tool vs search_files: use when client requires the 'id/title/url search contract (ChatGPT deep research)', otherwise prefer search_files for richer metadata. Also explains how result ids can be used with fetch/get_file, providing clear usage context.

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

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

Annotations declare readOnlyHint, openWorldHint, destructiveHint. The description adds behavioral details: returns processing status, ranking by name match, and always-allowed access. 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 the core action and resource, and a second sentence adding output and access context. 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?

Given an output schema (implied), the description covers input, behavior, and access. It lacks details on pagination, sorting, or error handling, but is sufficient for a straightforward search 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?

With 100% schema coverage, the description adds little beyond mentioning 'by filename,' which maps to the query parameter. The parameter descriptions in the schema are already detailed, so the description does not significantly enhance meaning.

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

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

The description clearly states the tool searches user files by filename, returns metadata with processing status ranked by name match. This distinguishes it from sibling tools like list_files (list all) and search (general search), providing specific verb and resource.

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

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

The description explicitly says 'Always allowed,' addressing authorization, but lacks guidance on when to use this tool over alternatives like search or list_files. However, the filename-scoped purpose is clear enough for typical use.

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

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

The description goes well beyond the annotations (readOnlyHint, destructiveHint) by detailing access re-checking, live validation, and graceful handling of revoked access ('calm no longer available note'). It also states 'Read-only; always allowed' and specifies exactly what is visible. This provides rich behavioral context beyond the annotations, which already indicate safety.

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

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

The description is front-loaded with the overall purpose. Each mode is explained in a dedicated section with clear labels (SAVED BY NAME, NETWORK, ORGANISATION). Despite its length, every sentence adds value—no filler. The structure makes it easy to scan and understand the complex behavior.

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 complexity (6 parameters, multiple modes, live access checking) and the presence of an output schema, the description covers all necessary aspects: listing vs reading, parameter relationships, access validation, and error handling. It also explicitly states limitations ('no directory or browse'). This is fully complete for an AI agent to select and 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?

Although the input schema already describes all 6 parameters (100% coverage), the description enriches each parameter with usage context: e.g., 'from' should come from a prior list call, 'saved' resolves via short name and re-validates access, 'handle' uniquely identifies a project, 'org'+'member' require shared organisation membership. This adds significant meaning beyond the schema descriptions.

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

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

The description clearly states the tool lists and reads curated personal context shared with the user. It provides distinct modes (list, read share, saved name, network handle, organisation teammate), each with specific verbs and resources. This differentiates it from sibling tools like profile, list_files, etc., which handle different domains.

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 each parameter mode: no arguments to list, 'from' for a specific share, 'saved' for a saved context, 'handle' for network context, 'org'+'member' for teammate context. It does not explicitly mention when not to use the tool, but the detailed guidance on each mode provides clear usage context. A slight omission of alternative tools (e.g., 'use profile for your own context') prevents a perfect score.

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 transparently discloses that the suggestion is pending, does not directly change the profile, and nothing is written to files. This adds significant behavioral context beyond the annotations which only indicate non-read-only and non-destructive.

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 with two front-loaded sentences: first stating the action, second explaining the behavioral implication. 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 existence of an output schema and the tool's complexity, the description adequately covers the nature of the suggestion and its scoping via handle/projectId. It could be slightly enhanced by mentioning how the user reviews the suggestion.

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

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

The input schema has 100% coverage with detailed parameter descriptions. The main description does not add additional semantic value beyond the schema, earning a baseline score 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 the tool suggests an update to user context, and distinguishes it from direct modifications by noting it saves as a pending suggestion. However, it does not explicitly differentiate from sibling tools like 'profile' or 'shared_context'.

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 context that the suggestion is pending and not directly applied, but it lacks explicit guidance on when to use this tool over alternatives like 'profile' for direct updates or 'shared_context' for reading others' context.

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