UseMyContext.ai

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces and expands on this by stating it is READ-ONLY, cannot change the plan or start a purchase, and that plan/billing changes are done by the user at usemycontext.ai. It adds meaningful behavioral context about side-effect safety beyond the structured annotations.

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

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

The description is front-loaded with the core purpose and use cases, and it provides useful exclusions and safety context. However, it is slightly redundant, repeating the read-only message multiple times ('This is READ-ONLY', 'Read-only; nothing is written'), which adds unnecessary length.

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

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

With zero parameters and an output schema present, the description covers everything an agent needs: what the tool does, when to use it, what it excludes, and its side-effect profile. The inclusion of the user-facing management URL adds practical context for follow-up actions.

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, so there are no parameter semantics for the description to clarify. Since no parameter documentation is needed, the baseline of 4 applies; the description appropriately focuses on the tool's scope rather than 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 uses a specific verb ('Report') and names the exact resource: the user's current plan and usage, including tier, projects, storage, subscription status, and plan management location. It also distinguishes itself from siblings by explicitly excluding files, facts, and profile content, making its scope unmistakable.

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

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

The description clearly states when to use the tool: when the user asks about their plan, usage against limits, or proximity to a limit. It also gives exclusions ('no files, facts, or profile content'), though it does not name alternative sibling tools explicitly, so it stops short of a full when-not/alternative guide.

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

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

Annotations already carry readOnlyHint=true and destructiveHint=false, so the safety profile needs no disclosure; the description adds return behavior beyond them — grounded passages with source citations and the division of labor that the agent must do the reasoning. The line 'Read-only; nothing is written, so it is safe to call' restates the annotation rather than adding new behavioral information, which keeps this from a 5.

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, with the core function and return contract front-loaded in the first sentence and the strongest usage directive (search before claiming ignorance) placed early. The final read-only sentence duplicates the annotations and is the only non-essential content, costing a point against an otherwise economical structure.

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

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

With a full output schema, 100% parameter coverage, and read-only annotations, the description only needed to cover selection and invocation judgment, which it does thoroughly: what it returns, when to prefer it over claiming ignorance, and the reasoning obligation on the agent. Nothing an agent needs to decide whether to call this tool correctly is missing.

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

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

All four parameters have rich schema descriptions (100% coverage), so the baseline is 3. The description adds one meaningful semantic layer beyond the schema: the query is interpreted 'by MEANING' rather than by keyword, which clarifies how to phrase the query parameter. It adds nothing about k, handle, or projectId, but those are already thoroughly documented in 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 names a specific verb and resource ('Search the user's connected documents by MEANING') and a concrete return contract ('the most relevant passages... each cited with its source file'). It actively distinguishes itself from siblings with the negative clause 'not a file link, not a filename list, and not a pre-written answer,' which separates it from get_file, list_files, and the other search tools. The title 'Ask your documents' is vague on its own, but the description fully disambiguates it.

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

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

It gives explicit when-to-use directives: 'Use this to ANSWER a question from the user's documents' and 'Before telling the user you do not know something about them or their work, search here first.' It states what it is not for ('not a file link, not a filename list... you do the reasoning') and the handle parameter names a concrete alternative ('use shared_context instead') for reading context someone else shared, routing the agent away from the wrong tool.

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

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

Annotations already 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?

The description goes beyond the readOnlyHint annotation by detailing concrete limitations: cannot create/rename/delete profiles, change privacy, manage billing, set up teams, invite teammates, or connect third-party services. It also discloses that it returns static public information only and no user data, and reassures that nothing is written. This gives the agent a complete safety and behavior profile.

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

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

The description is well-structured with a clear opening purpose, explicit trigger conditions, an IMPORTANT limitations section, and a return-safety note. It is slightly redundant at the end ('Read-only; nothing is written' repeats earlier statements), but the information is front-loaded and each section earns its place.

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

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

For a zero-parameter, read-only informational tool with an output schema and readOnlyHint annotation, the description is complete: it states the purpose, when to use it, what not to attempt, where to redirect users, and what kind of data it returns. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The tool has no parameters, so the baseline of 4 applies. The description does not need to explain parameter semantics because there are none; it instead clarifies what information the tool returns, which is the relevant semantic content for this no-input tool.

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

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

The description uses a specific verb ('Explain') and names the exact resources covered: what UseMyContext is, what the connection can and cannot do, and where to manage the account. This clearly differentiates it from siblings like account, profile, or suggest_update by emphasizing it is informational and read-only.

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

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

It explicitly states when to call: 'Call this when the user asks what UseMyContext is, what you (the AI) can do with this connection, or where to find pricing, plans, billing, teams, or settings.' It also gives clear negative guidance: the AI cannot perform account/admin actions and should instead point the user to returned links. This provides both inclusion and exclusion criteria.

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

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

Beyond the annotations, the description discloses that the operation is metadata-only, that nothing is written, and that file status includes a readiness delay with queueEtaSeconds for recently processed files. It also explicitly says it is safe to call, reinforcing the read-only behavior with useful operational detail.

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 tight sentences: the first front-loads the core purpose and output fields, and the second explains status semantics and safety. Every sentence contributes meaning, with no filler or repetition of schema details.

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 is complete given the rich input schema, output schema, and annotations. It covers the return scope, status interpretation, related tool behavior, and safety profile, leaving no critical guidance missing for an 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 description coverage is 100%, with both handle and projectId thoroughly documented in the input schema. The tool description adds no parameter-specific meaning, so it receives the baseline score for relying on the schema rather than compensating for any gaps.

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

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

The description states a specific verb ('List'), a clear resource ('the user's files'), and a precise scope ('metadata only: id, name, size, content-type, modified, status'). It also distinguishes itself from related tools by referencing get_file for reading content and ask_docs for searchability, making the tool's role unambiguous.

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

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

The description gives clear context: list_files is for viewing metadata and status, while get_file reads the actual content and ask_docs handles search readiness. It does not explicitly list exclusions or say 'use this instead of search_files,' but the intended usage is clear and no misleading guidance is present.

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 reinforces the readOnlyHint annotation by stating 'Read-only; nothing is written, so it is safe to call.' It also adds beyond annotations by disclosing that only metadata is returned—no file content, facts, or compiled context—which gives the agent a precise model of the tool's behavior.

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

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

The description is somewhat long but every sentence adds actionable content: purpose, return metadata, use cases, exclusions, and safety. The no-content phrasing ('No file content, no facts, no compiled context') slightly repeats the 'metadata only' point, but the structure is otherwise efficient and front-loaded.

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

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

For a parameterless, read-only tool with an output schema, the description is fully complete. It tells the agent exactly what the tool returns, when to invoke it, when to avoid it, and which sibling to use instead. No critical information is missing.

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

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

The tool has zero parameters, so there is no parameter documentation burden. The schema's coverage is effectively 100% with an empty properties object, and the description appropriately focuses on behavior and output rather than 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 states a specific verb and resource: it lists the user's own profiles and specifies the exact metadata fields returned. It also explicitly differentiates from the sibling 'profile' tool, making it impossible to confuse the two.

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

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

The description gives clear when-to-use cases: counting profiles, naming profiles, identifying the connected profile, and supplying projectId to other tools. It explicitly says when NOT to use it, pointing to the 'profile' tool for reading context or setting up UseMyContext.

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

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

The description discloses key behaviors beyond the readOnlyHint annotation: it is read-only and safe to call, returns setup instructions on an empty profile versus context on an established one, contains no file content, and reports privacy status. This adds meaningful operational context without contradicting 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 longer than average but every section earns its place: core purpose, when to call, onboarding triggers, behavior on empty profiles, sibling differentiation, safety, and privacy output. It is front-loaded with the main verb and resource, and the additional length is justified by the tool's dual-purpose nature.

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

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

Despite the tool's dual use and subtle account-wide vs single-project scoping nuance, the description covers usage timing, alternative tools, safety, empty-profile behavior, and output highlights. The output schema exists, so return-value detail does not need to be repeated. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the input schema already fully documents both handle and projectId, including precedence, scoping behavior, and invalid-handle handling. The tool description itself adds no parameter-level information, but per the baseline for high schema coverage, a 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Return the user's compiled personal context - a compact structured summary of who they are.' It clearly distinguishes this from siblings like list_profiles ('it only lists each profile's name, @handle, and privacy status') and shared_context ('To read context someone ELSE shared... use shared_context instead'). Its dual role of onboarding is also explicitly stated.

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

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

Gives precise when-to-use guidance: 'Call it at the start of any conversation that involves the user personally' and identifies exact trigger phrases for onboarding ('set me up with UseMyContext', 'get me started', etc.). It also explicitly warns against the wrong alternative ('Do not reach for list_profiles for any of that') and directs users 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?

Beyond the readOnlyHint=true annotation, the description discloses deterministic full-scan semantics ('executes over EVERY row and returns exact numbers'), case-insensitive column and text matching, and that non-numeric cells are skipped and counted in skippedNonNumeric. It also reveals error-recovery behavior (invalid columns produce an error listing the real columns) and the default/max row limits. 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?

Long but dense and front-loaded: purpose and sibling routing lead, the grammar is compressed into one structured JSON sketch, and three examples illustrate real invocations. Every sentence earns its place, including the error-recovery and safety notes; the only mild redundancy is reaffirming read-only, which functions as a deliberate safety emphasis.

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

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

For a tool with a nested query object, 7 operators, and 5 aggregate functions, the description covers file-format scope, full query grammar, operator semantics, limits, error behavior, and safety; the output schema covers return values, and handle/projectId semantics are thoroughly documented in the schema itself. Nothing an agent needs to invoke it correctly is missing.

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

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

With 100% schema coverage the baseline is 3, but the description carries the full query grammar that the schema explicitly defers to ('grammar in the tool description'): select/where/groupBy/aggregates/limit, per-operator semantics (eq|neq|contains case-insensitive; gt|gte|lt|lte numeric), the count exemption from col, and the default 50/max 200 limit — plus three concrete examples. It adds far more meaning than the schema's stub 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 a specific verb and resource — 'Run an EXACT, deterministic query over ONE tabular file' — and names the covered formats (CSV, first table of spreadsheet/PDF/Word). It explicitly contrasts with ask_docs ('semantic search undercounts tables') and get_file, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives explicit when-to-use conditions: use it instead of ask_docs whenever the question needs COUNTING, SUMMING, AVERAGING, MIN/MAX, FILTERING, or exact row lookups, with concrete example phrasings ('how many rows...', 'total amount by region'). It also states what the alternatives are for — 'Use ask_docs for prose/meaning questions and get_file to read a whole document' — leaving nothing to inference.

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

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

The description aligns with annotations (readOnlyHint=true, destructiveHint=false) and adds useful behavioral context: it is the same search as search_files with the same permissions, is read-only, and returns result ids that can be passed to fetch or get_file. This goes beyond the structured annotations and clarifies side effects precisely.

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 primary purpose, then efficiently covers alias identity, invocation criteria, result usage, and safety in a few dense but relevant sentences. No filler or redundant restatement of the schema exists.

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 search tool with three parameters and an output schema, the description fully covers how to invoke it, when to prefer siblings, how scoping works, and what to do with results. Given the annotations and schema already present, nothing necessary for correct use is missing.

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

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

Although the schema already covers 100% of parameters, the description adds valuable semantic detail: handle takes precedence over projectId, both are honored only for account-wide connections, invalid handles are refused outright, and shared_context is the alternative for others' shared content. This meaningfully enriches the schema definitions.

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

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

States a specific verb ('Search'), resource ('user's files'), and scope ('by filename'), and defines the output contract ('deep-research result shape'). It also distinguishes itself from search_files by explicitly labeling this the same search with a different result contract, so an agent can differentiate siblings immediately.

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

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

Provides explicit when-to-use guidance: use this tool when the client requires the id/title/url search contract, otherwise prefer search_files for richer metadata. It also explains handle/projectId scoping behavior and directs shared-context access to shared_context, leaving no ambiguity about 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 mark readOnlyHint and destructiveHint, and the description reinforces safety with 'nothing is written.' It adds non-obvious behavior beyond annotations: returns processing status, ranks by name match, and refuses an invalid handle outright rather than silently swapping 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?

Three sentences cover purpose, return value, and safety. The information is front-loaded and each sentence earns its place with no filler or repetition.

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

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

With an output schema present and detailed parameter descriptions, the description explains the tool's purpose, result contents, ordering, and safety. It also discloses edge-case behavior for invalid handles, giving an agent everything needed to decide whether to call 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?

Schema description coverage is 100%, with query, handle, and projectId each fully documented including precedence and scoping behavior. The tool description itself adds no parameter-level information beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Search the user's files by filename.' It also explains what is returned (file metadata including processing status, ranked by name match), which clearly distinguishes it from sibling tools like search, list_files, and get_file.

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 main description implies usage by scoping to the user's files, and the handle parameter explicitly says to use shared_context instead when reading someone else's shared context. It does not explicitly contrast with list_files or search, but the scoping and alternative routing provide 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 already supply readOnlyHint and destructiveHint, and the description adds substantial behavior beyond them: live access re-validation on every call, graceful 'no longer available' note instead of an error when access is revoked or expired, the closed-world guarantee ('only ever see what was shared with you, saved by you, opened to the network, or a teammate's context'), and the one-handle-per-project invariant. The repeated read-only line merely reinforces the annotations without contradicting them.

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

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

Long, but the length is earned by four distinct usage modes, and the description is front-loaded with its core purpose before CAPS-LABELED mode sections make it scannable. Minor redundancy keeps it from a 5: the 'handle alone identifies what to read' point and the directory URL repeat schema text, and the read-only sentence duplicates annotation data.

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

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

For a tool with zero required parameters and six optional ones across four modes, the description covers every mode's trigger, inputs, access preconditions, failure behavior, and scope boundaries. An output schema exists so return values need no prose coverage, and annotations cover the safety profile; no critical operational gap remains.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by organizing the six parameters into mutually exclusive usage modes, stating which params combine (`org` with `member`, `orgProject` only alongside both), and explaining resolution semantics (`saved` resolves a name to its real source) beyond what per-parameter schema text conveys. A 5 would require it to carry information the schema genuinely lacks, but the schema is already rich.

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

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

Opens with a specific verb+resource pair, "List and read curated personal context shared with you," and enumerates four distinct read modes (list, from, saved, handle, org+member). This cleanly separates it from siblings like list_files, get_file, profile, and search by anchoring the tool to shared/saved/network/team context rather than files, facts, or general 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?

Provides mode-by-mode when-to-use guidance: no args lists, `from` reads a listed share, `saved` pulls by a user-chosen name, `handle` targets a network project, and `org`+`member` reads a teammate's composite. It also states access preconditions and boundaries (public directory vs. needing known ids, 'curated context only, never their files or facts'). It stops short of a 5 because it never explicitly names a sibling alternative or states when NOT to use this tool in favor of another.

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 annotations only convey readOnlyHint=false, but the description adds critical behavioral nuance: the update is pending, does not directly change the profile, and never modifies user files. This is exactly the non-obvious behavior an agent needs to understand before calling the tool.

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

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

The description is focused and efficiently opens with the action and its pending, non-destructive nature, then gives the concrete usage window. No filler or redundant elaboration is present.

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

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

The description covers the purpose, the exact trigger moment, the safety model, and what is not affected, and the output schema exists so return values need no elaboration. An agent has enough to know when to use this tool and what outcome 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?

Schema description coverage is 100%, and each parameter is already well documented with its own description. The tool description adds behavioral context but does not add beyond the parameter schemas, so a baseline of 3 is appropriate.

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

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

The description clearly states what the tool does: it proposes a profile update for the user to review, not a direct change. This distinguishes it sharply from direct update or write tools and conveys an actionable resource and outcome.

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

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

It explicitly specifies when to use it: when a conversation surfaces new durable user information and is wrapping up with thanks, goodbye, or task completion. It also contrasts with shared_context for reading others' shared context, giving the agent clear routing guidance.

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