X1 Wealth

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description goes beyond them by disclosing response behavior — it cites source and page, and explicitly says it will state plainly when it lacks an answer — plus the scope limitation to the connected person's household. That is meaningful added context for a Q&A 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?

A single dense sentence that front-loads the core purpose and appends scope and behavioral caveats; there is little waste. It is somewhat run-on, packing citation behavior, failure mode, and scope exclusions into one clause chain, but nothing is redundant.

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

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

With annotations covering the safety profile and an output schema handling return values, the description supplies what remains: query scope, citation behavior, and the no-answer fallback. It is essentially complete for this tool; only explicit routing to alternative tools for out-of-scope questions 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% and both parameters are documented in the schema, including the record enum and the question length bounds. The description adds no syntax, format, or interpretation guidance for the parameters 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?

States a specific verb ('answers questions') and a precisely scoped resource (the connected person's own household record — trusts, entities, properties, insurance, decisions, documents). It also explicitly distinguishes itself from sibling read tools by naming what it does not do (does not track balances or spending), so an agent can separate it from get_household_financial_snapshot or search_my_document_contents.

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 clear context for use: ask about the connected person's own family finances and what their documents say, from the X1 household record or kept documents on outside assistants. It adds a negative boundary (only the connected person's own household, no balances/spending) but does not name a specific alternative tool for those excluded cases, so routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds two things not in structured data: it never returns an upload link or token, and it can report an intermediate 'still reading' state that the agent should surface and then re-check. Error cases (expired token, unknown requestId, how long to wait) are not covered.

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

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

Front-loaded with the purpose, then the parameter rules, then the response handling, then the self-only constraint — a sensible order with no filler. Some sentences are dense and pack two ideas (e.g., the still-reading instruction), but every sentence carries operational weight.

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

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

With no output schema, the description compensates by naming the two observable outcomes (arrived vs. still reading) and one guaranteed non-return (no link/token), plus the self-only scope. It falls short of covering failure modes and expected polling latency, which an agent may need in practice.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the selection logic the schema only implies: requestId is the normal path when the upload tools are mounted, token is the fallback for a direct dropUrl call. Both parameters are optional, and the description clarifies when each 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?

States a specific verb (check), resource (a file deposit), and scope (THEIR OWN X1 documents), which separates it from listing tools like get_vault_documents or search_my_documents. It also names the upstream tools whose requestId it consumes, so an agent knows exactly where this sits in the approval-to-deposit flow.

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 conditional invocation rules: pass requestId when request_vault_upload_link or create_my_vault_upload are mounted (the usual path), pass token only when a direct call returned a dropUrl. It also prescribes the follow-up behavior in each outcome, which resolves the ambiguity about whether to answer the user or keep waiting.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description still adds real value: it discloses that the operation is a draft that does not open a browser, that guardrails are read/download-only, and that an X1-side confirmation review is required. That is meaningful behavioral context beyond the annotations.

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

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

Two tight sentences, front-loaded with the verb and resource, with no filler. The second sentence is dense but its enumeration of return contents is purposeful, so it stays structurely efficient overall.

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 compensates for the absent output schema by enumerating what gets returned (goal, domains, guardrails, review contract), and annotations cover safety. However, with 6 undocumented parameters at 0% coverage, the definition leaves a notable gap an agent must fill blindly.

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 6 parameters at 0% schema description coverage, the description carries the full burden but only gestures at two of them (goal, allowed domains) as return fields rather than input semantics. The other four (clientId, clientRef, institutionLabel, targetArtifactLabel) get no guidance, format, or constraint hints.

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

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

The description opens with a specific verb+resource ("Draft an Ask X1 BrowserMission proposal") and immediately scopes the operation with "without launching a browser session," which cleanly separates it from execution/launch and from siblings like get_browser_mission_status and summarize_browser_mission_result.

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 "without launching a browser session" clause and "for X1-side confirmation" hint at when this pre-step applies, but there is no explicit statement of when to choose this over its siblings (e.g. status or summarize tools) or any stated prerequisites. Usage is implied rather than directed.

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/idempotent/non-destructive, and the description reinforces with 'writes nothing' without contradiction. It adds real behavioral context beyond annotations: the optional insight is treated as unverified external evidence bound to the exact live thread revision before review, and missing outcomes prompt a request instead of a guess.

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 front-loaded sentences: purpose, evidence-handling, and write/no-write routing. Efficient overall, though the middle sentence is dense with jargon ('source-minimized', 'live X1 thread revision') that slightly slows comprehension.

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 5-parameter tool with a nested object and no output schema, the description covers purpose, the write-free guarantee, the actual closing mechanism, and the missing-outcome edge case. Return-value detail is not required without an output schema, so coverage is nearly complete.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds behavioral meaning for parameters: it explains the optional sourceProposal's unverified/hash-bound nature and that an omitted closeoutOutcome causes the tool to ask rather than infer. This meaningfully supplements the structured fields.

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 ('Draft a proposed coordination-thread closeout summary with citations...'), and distinguishes itself from the draft_coordination_reply/draft_coordination_thread siblings by being specifically a closeout. It also names the sibling that actually performs the closing (close_coordination_thread).

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

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

Clearly routes the agent: 'This tool writes nothing; closing happens through close_coordination_thread when it is mounted, or in X1,' and says to ask for a missing outcome rather than guess. It gives strong context but never directly contrasts with the other draft_* siblings, so an explicit when-not comparison is absent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: it explains that the call loads the thread and returns its latest messages as citations, that replyGoal becomes the draft body, and that nothing is written. It stops short of describing the commit/confirmation flow in any detail despite advertising 'human-confirmation commit instructions'.

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 purpose followed by the read-first caveat and the write boundary; there is little waste. It is slightly dense, packing return behavior, parameter mapping and the send alternative into the second sentence, but nothing is filler.

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

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

With no output schema, the description carries the burden of explaining returns, and it does state that the tool returns the thread's latest messages as citations plus a draft packet. Combined with the 100% schema coverage and read-only annotations, an agent has enough to invoke it correctly; only the promised 'commit instructions' are never actually described.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns an extra point by tying semantics to behavior that the schema does not: replyGoal 'becomes the draft body' and threadId is the thread whose 'latest messages' are returned as citations, which is more than the schema's terse 'Plain-language intent' and 'Coordination thread 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 states a specific verb and resource ('Draft a proposed coordination-thread reply') and immediately scopes the deliverable ('with citations and human-confirmation commit instructions'). It also distinguishes itself from the send-side sibling by naming reply_to_coordination_thread, so an agent can tell drafting from sending 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?

It gives a clear usage condition ('read the thread first when the reply has to answer its content') and an explicit boundary against a named alternative ('This tool writes nothing; sending happens through reply_to_coordination_thread when it is mounted, or in X1'). What it does not do is disambiguate itself from the other drafting siblings such as draft_coordination_thread or draft_coordination_closeout, which remains an inference 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 already declare readOnly/idempotent/non-destructive, so the bar is low, yet the description adds real context: the tool returns availableRecipients, unknown recipientIds are refused, and use is gated by mounting and actor safety ('when it is mounted and the current actor can safely use it'). The mounting/permission phrasing is a bit vague, keeping it 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?

Purpose is front-loaded, but the second sentence runs long with an awkward clause ('when it is mounted and the current actor can safely use it') that is vague and hard to act on. Two dense sentences with some redundancy ('This tool writes nothing' repeated in the message schema).

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

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

No output schema exists, yet the description explains the key return value (availableRecipients) and the refusal behavior, and annotations cover the safety profile. The workflow role relative to start_coordination_thread is conveyed, though the 'mounted' prerequisite remains underspecified.

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, but the description adds meaning beyond the schema: recipientIds must be drawn from the returned availableRecipients and unknown IDs are refused, and it clarifies clientId omission for one's own household. This enriches the recipient/client semantics materially.

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 ('Prepare a new coordination-thread draft') and enumerates what the draft carries (member, recipients, subject, message). It is distinguishable from sibling drafts like draft_coordination_reply and draft_coordination_closeout, though it never explicitly contrasts itself with them.

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 clear sequencing guidance: call it before looking up a professional elsewhere, and note that it produces commit instructions for start_coordination_thread. It does not spell out when NOT to use it versus the other draft_* siblings, but the workflow placement is explicit.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is already covered. The description adds genuine value beyond that: 'nothing is saved or sent' and it 'Returns a proposal and the X1 review destination,' clarifying the dry-run nature and the follow-on step.

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 tightly scoped sentences that front-load the action and the no-side-effect guarantee. No filler, though the category constraint sentence is somewhat redundant with the schema's category description.

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 100% schema description coverage, the description needn't detail return values, yet it still signals the proposal-and-review-destination output and the 'nothing saved/sent' behavior. Complete enough to call the tool correctly; only explicit sibling routing is absent.

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 every parameter including enums, deadlines, and clientId is already documented in the schema. The description only restates the category constraint and examples the schema also provides, so the baseline of 3 is appropriate for this schema-driven 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 states a specific verb and resource: 'Prepare a draft request for a missing financial or household document,' with concrete examples (K-1, statement, trust, property record). This distinguishes it from the sibling list_document_requests, though it does not explicitly name an alternative. Purpose is clear without opening the schema.

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

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

It implies the usage context ('for a missing ... document') and adds the constraint that only supported categories on this connection can be requested. However, it never states when to use this draft tool versus siblings like list_document_requests or other draft_* tools, leaving routing to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, and the description reinforces this with substantive extra context: it is 'write-nothing', 'deterministic', 'never merges records', and explicitly 'has no MCP confirm tool', plus it delivers a consequence preview and X1 deep link. This prevents an agent from hunting for a confirm tool that 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 sentences, zero waste. The core purpose is front-loaded and the second sentence is load-bearing because it corrects the dangerous implication of the word 'merge'.

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, return values need not be explained. The description fully covers what is produced, that no write occurs, and where the follow-up confirmation lives — everything an agent needs to 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?

Schema description coverage is 100%, so loserEntityId/survivorEntityId/clientId/clientRef are already documented in the schema. The description only implies the two-item pairing and adds no syntax, format, or sourcing detail beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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?

Names a specific verb (prepare a proposal) and resource (two member-owned household items that may be the same), and immediately distinguishes itself from any actual merge tool by stating it 'never merges records'. An agent can tell exactly what this produces without reading the schema.

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

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

The use condition is stated ('two member-owned household items that may be the same'), and the description clarifies that confirmation happens first-party in X1 rather than via any MCP tool, which routes the agent correctly. It stops short of naming specific siblings (e.g. list_household_entities as the ID source or list_household_entity_change_proposals) or stating explicit when-not conditions.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description nonetheless adds concrete behavioral facts: it self-gathers meeting prep, validates recipients against an allowed team list (arbitrary users rejected), and creates no packet or relationship. The 'writes nothing, sends nothing' clause partly restates the annotations, 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?

Three sentences, each doing distinct work: what it produces, how to route to it, and what it does not do. The core purpose is front-loaded and there is no filler or 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?

For a read-only drafting tool with no output schema, the description covers purpose, routing, side-effect scope, and the key validation constraint, which is enough to invoke it correctly. It stops short of describing the brief's structure or length beyond the 'omitted sections' hint, but nothing critical 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 every parameter (title, purpose, audience enum, clientId, meetingDate, recipientIds) is already documented in the schema. The description echoes the recipient-eligibility and self-household drafting rules but adds no new syntax, format, or interaction detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb (prepare/draft) plus the resource (a role-aware meeting, intro, or handoff brief) and adds a scope constraint ('from data the actor can already read'). It also implicitly separates itself from the sibling get_meeting_prep by stating 'It gathers meeting prep itself, so call it directly,' so an agent can route without opening a schema.

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

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

It explicitly tells the agent to call this tool directly and to consult other tools only for sections the brief marks as omitted, which is a clear when-to-use rule plus a named alternative behavior. It also flags the recipient-eligibility precondition (must come from the member's allowed team list), covering the main failure mode before invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the important scoping constraint that results stay within the caller's household or participant/watcher scope, which is useful non-annotation context, but says nothing about result ordering, pagination beyond the limit parameter, or completeness of results.

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

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

Two sentences, no waste. The search action and its filter dimensions are front-loaded, followed by the scope constraint. Efficient and well-structured.

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

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

For a 9-parameter search tool with no output schema, the description covers the main facets and the scope constraint but leaves gaps: no return shape information, no pagination behavior, and no explicit routing guidance among similar siblings. Adequate but with clear 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 description coverage is 56%, so roughly half the parameters are documented. The description adds the list of filterable dimensions (query, participant, status, intent, closeout outcome, activity date range) which maps to the parameters, but adds no syntax or format detail beyond what the schema already provides for the documented ones.

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+resource ('Search coordination threads') and enumerates the filterable facets. It is distinguishable from sibling list_my_coordination_threads and get_coordination_thread, though it does not explicitly name those alternatives.

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

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

Usage is implied by the filter enumeration and the scope note, but there is no explicit statement of when to use this tool versus list_my_coordination_threads, get_coordination_thread, or summarize_coordination_thread. The agent must infer the selection 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the description adds value beyond them by disclosing two real behavioral traits: it never launches a browser or sends anything external, and it fails closed as 'infra_gated' when BrowserMission storage is unavailable. That failure-mode disclosure is genuinely useful for an agent interpreting a result.

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 tight sentences with zero filler, front-loading what is read before the behavioral guarantees. Every clause 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 single-parameter read tool with no output schema, the description covers purpose, side-effect profile, and the failure mode. It does not describe what the returned status values look like, but that is a minor gap given the tool's simplicity.

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

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

One parameter with 0% schema description coverage, so the description must compensate. It only restates that missionId identifies the BrowserMission ('by missionId'), adding no format, source, or lookup guidance beyond the schema's type and required flag. Adequate but thin.

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 ('Read the X1-owned status of a BrowserMission by missionId'), which is distinguishable from siblings like summarize_browser_mission_result or draft_browser_evidence_mission. It doesn't explicitly name an alternative sibling, but the scope is 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?

Usage is implied by the definition ('read the status of a mission by id') but there is no explicit when-to-use guidance or routing away from the similar summarize_browser_mission_result sibling. An agent can infer the case but must do so itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real behavioral context: results are 'bounded', raw claims and evidence are opt-in, and access is permission-gated ('excluded unless a future explicit permission adds this surface'). It doesn't disclose pagination or default return shape, keeping it out of the top tier.

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?

It is a single dense sentence with nested parentheticals and a mid-sentence colon example, front-loaded with the core verb but heavy to parse. No outright waste, yet the run-on construction hurts readability.

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

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

With no output schema and 0% schema coverage across 6 parameters, the description should do more. It covers purpose, ownership semantics, and permission gating well, but omits any explanation of the parameters or the returned claim structure an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the param burden. It hints at includeRawClaims/includeEvidence ('optional raw claims and evidence'), scope ('member or household'), and limit ('bounded'), but leaves clientId, memberIds, and actual limit bounds entirely undocumented. Partial compensation only.

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 ('Return') and resource ('bounded business-entity graph claims for a member or household'), and elaborates on a distinctive output, effectiveOwnership look-through with a concrete example. This clearly separates it from generic context tools, though it never names a specific sibling like get_professional_graph_context or list_household_entities.

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

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

It provides an implied usage goal ('so you can answer what they effectively own through their entities') and notes an exclusion ('Scoped specialists are excluded'), but gives no explicit when-to-use versus alternatives or prerequisites for choosing this over list_household_entities or get_family_office_context. Usage is inferable rather than directed.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is partly covered. The description adds genuine value beyond that by enumerating the possible status outcomes and explicitly stating it is 'never authority to move money or proof of settlement', which tells the agent what the status does NOT grant.

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 action and resource, then the status outcomes. Every clause carries information; the second sentence is dense but earns its length by enumerating states and limits.

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

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

An output schema exists, so return-value explanation is not required, and the description still usefully previews the status enumeration. Combined with annotations it is nearly complete, with the only real gap being sibling disambiguation from get_capital_call_source_state.

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

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

Schema description coverage is 100% for the single documentId parameter, so the baseline is 3. The description reinforces that the job is tied to 'one exact document in your own X1 Vault', but adds no format or constraint detail beyond what the schema already states.

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 (Read) and resource (capital-call job) scoped to one exact document in the user's X1 Vault, so intent is unambiguous. However, it never distinguishes itself from the very close sibling get_capital_call_source_state, leaving the agent to infer which state to fetch.

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

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

Usage is implied by the phrasing ('Read the existing capital-call job'), but there is no explicit when-to-use, no exclusions, and no routing to alternatives such as get_capital_call_source_state. The agent must infer selection from context alone.

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 it as a read-only, idempotent, non-destructive, closed-world call, and the description adds real behavioral context on top: it returns either complete proof-backed facts or a typed hold, and explicitly disclaims confirmation, obligation creation, write authorization, money movement, and settlement verification. That is substantive disclosure beyond the annotation set.

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

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

Two front-loaded sentences with no filler, and the core action leads. The second sentence is a dense negative clause list that is slightly jargon-heavy ('strict source-state projection', 'typed hold'), but every clause carries scope information.

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

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

With an output schema present, the description need not detail return shape, and it still conveys the semantic return contract (facts vs. typed hold) and the capability boundaries. The only gap is the absence of guidance on when to choose this tool over sibling lookups such as get_capital_call_job_state.

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

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

Schema description coverage is 100% for the single documentId parameter, and the description adds no format or sourcing detail beyond what the schema already says. Baseline 3 is appropriate when the schema does the work.

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

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

States a specific verb ('Read') and resource ('one capital-call notice from your own X1 Vault') and frames the scope ('strict source-state projection'). It implicitly separates itself from the similarly named sibling get_capital_call_job_state, but the distinction is left to be inferred rather than 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?

There is no explicit when-to-use guidance or named alternative; the agent must infer usage from the name and the pipeline hint in the schema ('documentId returned by get_vault_documents'). The negative list (never confirmation, obligation, write, coordination, money movement, settlement) clarifies scope boundaries, which is useful, but those are exclusions rather than usage directions.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the useful scope note that it is a 'broad timeline' and access-limited ('a client/member you can access'), but says nothing about pagination, ordering, or what an activity item contains.

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

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

Three short sentences, front-loaded with the core action, then utility, then routing. No filler, and each sentence earns its place, though the third reads slightly redundantly with the second.

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

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

With no output schema, the description should convey what comes back; 'recent activity timeline' gives a rough shape but no detail on item contents or ordering. For a simple read-only, two-parameter tool whose annotations cover safety, this is adequate but leaves 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 description coverage is 100%, so both parameters (limit, clientId) are already documented in the schema. The description adds no meaning beyond it — it never mentions the limit cap or the clientId format. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource ('Get a recent activity timeline') and clarifies scope ('for yourself or a client/member you can access'). It also positions itself against alternatives by contrasting the 'broad timeline' with shared documents and coordination threads, which helps distinguish it from the many get_* siblings.

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

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

It states when it is useful ('understanding engagement and what changed recently') and gives an explicit when-not-to-use with an alternative ('Scoped specialists should use shared documents and coordination threads instead'). That routing guidance is stronger than most siblings, though it doesn't spell out prerequisites or exclusions beyond specialist roles.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description does add real value beyond that: totals are connected-account-only, the documentBacked figures are as-of statement date and never live, and account/loan numbers are truncated to last four. This is substantive behavioral context layered on top of 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?

Front-loaded with the core purpose before the caveats, and every clause carries information. It is dense to the point of being a single sprawling block, and the documentBacked aside could be tightened, but nothing is pure filler.

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

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

With an output schema present, return values need not be explained, yet the description still clarifies the entity spine, the connected-account-only basis, and the statement-date nature of documentBacked data. An agent has everything needed to call it correctly and interpret the result.

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

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

Only one parameter and schema coverage is 100%, so the baseline is 3. The description's clientId sentence is essentially verbatim what the schema already documents, adding no new syntax, format, or validation meaning.

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

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

States a specific verb and resource ('Get connected-account liquidity broken out by entity') and immediately scopes it: cash, investments, debt, net connected value per entity plus household total. It also draws a hard boundary against neighboring concepts ('Connected accounts only in the totals, not full net worth'), which separates it from broader snapshot tools.

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

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

Gives concrete caller-dependent guidance: members may omit clientId for their own record, professionals must pass it unless X1 already supplied a client-scoped context, and scoped specialists are excluded. It does not name a sibling alternative for the full-net-worth case, so the routing is clear but not fully explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real value beyond them: the draft-visibility privacy rule and the exclusion of scoped specialists, which an agent could not infer from structured fields.

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

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

Three dense sentences with no filler and the scope/ownership rule front-loaded. The first sentence is slightly overloaded with the field list, but nothing is wasted.

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

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

No output schema exists, and the description compensates by naming the returned fields and the privacy semantics of drafts. Combined with complete parameter documentation, an agent has enough to invoke it correctly, though pagination/ordering behavior is not stated.

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 reinforces the drafts enum semantics ('only pending drafts written by the connected user') and enumerates the returned fields (category, timestamps, status, owner labels, confidence, provenance), adding meaning beyond the schema for a tool with no output schema.

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

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

States a specific verb (Recall) and resource (recorded X1 decision memory) plus the scope (own record or assigned client) and the dimensions available. An agent can distinguish this from get_client_profile or get_client_activity without opening schemas.

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

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

Explains the ownership rule (own record vs assigned client, professionals must pass clientId) and gives explicit conditional guidance for the drafts mode. It also states exclusions ('every other professional draft remains private', 'Scoped specialists are excluded'), but never names a sibling as an alternative.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful access-scoping context (yourself or an accessible client/member; scoped specialists excluded), but says nothing about return shape, pagination, or freshness of the aggregated data.

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

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

Two sentences with the action front-loaded and the access constraint following. The enumeration is dense but each item adds informational value rather than padding.

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

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

With no output schema, the description must convey what comes back, and it does by listing the product-state components. For a read-only aggregation tool with full annotation coverage, this is nearly sufficient; only the absence of any note on data currency or scope limits holds it back.

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

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

Schema description coverage is 100% for the single optional clientId parameter, so the schema carries the semantics. The description reinforces that the target may be yourself or a client/member, but adds no format or behavior details beyond the schema; baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('structured view') and enumerates the surfaces it aggregates (onboarding, Pulse, vault, plays, packet readiness, member-intelligence, CRM context). An agent can grasp what it returns, though it does not explicitly differentiate itself from siblings like get_client_profile or get_household_financial_snapshot.

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

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

Specifies the eligible subject ('for yourself or a client/member you can access') and an access exclusion ('Scoped specialists do not receive this broad product-state surface'), which is useful routing context. However, it never says when to prefer this aggregated view over narrower siblings, so the when-to-use guidance is only implied.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely useful context beyond them: role-based access model, admin-only read-only break-glass escalation, and the currentFacts semantics (client-shared facts plus document-derived facts with document/page/section but never quoted text). This materially exceeds the annotation payload.

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

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

Front-loads the core purpose well, but the remainder is dense with specialized jargon ('bounded shared member intelligence', 'currentFacts', 'X1 read from documents') that is not self-explanatory and reads as internal shorthand. Every sentence is relevant, yet the phrasing is more convoluted than it needs to be.

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 read-only tool with full annotation coverage, a 100%-covered schema, and no output schema, the description supplies the access model and the semantics of the returned facts. It is largely complete; only the return-shape and how it differs from sibling client getters are left implicit.

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 clientId, clientEmail, and debugAccess are already documented in the schema. The description restates debugAccess semantics ('read-only break-glass when eligible') but adds no new syntax, format, or precedence detail, so baseline 3 applies.

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

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

States a specific verb and resource: 'Canonical MCP read for your profile or a profile view for a client/member you can access.' The scoping (own profile vs. an accessible client/member profile) is clear, but it never names or contrasts with the many sibling get_client_* tools (activity, liquidity, memory, tax_reserve), so an agent must infer the boundary.

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 actor-specific context ('Advisors use active relationships, coaches follow managed-program defaults, and scoped admins can use debugAccess'), which implies usage but is not framed as when-to-use-this vs. an alternative. No explicit exclusions or sibling routing, so guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: data provenance ('as X1 read them from returns you can see', household confirms in X1), and important caveats that this is a planning estimate, not tax advice, federal income tax only. It does not, however, discuss any rate limits or freshness/latency 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 leading clause front-loads the core purpose before the field inventory, and the caveats are grouped at the end. The middle sentence enumerating every returned subfield is dense and slightly run-on, but with no output schema it is largely load-bearing rather than filler.

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

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

With no output schema, the description appropriately documents the return shape (reserve fields plus filedReturns and informationReturns subfields) and carries the necessary scope and disclaimer context. The main omission is explicit guidance on when to prefer this over sibling client-state tools, and there is no mention of pagination or empty-result behavior.

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

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

Schema description coverage is 100% and there is a single optional parameter, so the schema already fully documents clientId, including the member-omit/professional-must-pass rule. The description's reference to 'your own record or an assigned client' restates rather than extends that, so the 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?

States a specific verb ('Get') and a precisely scoped resource ('federal estimated-tax reserve planning position'), then enumerates the concrete fields returned (target reserve rate, safe-harbor amount, next deadline, provenance). It also explicitly disentangles itself from the filedReturns/informationReturns payloads by noting those 'do not drive the reserve position', which helps an agent distinguish this from sibling client-state tools like get_client_liquidity.

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 establishes eligibility ('your own record or an assigned client') and notes that 'scoped specialists are excluded', which is real usage context. However, it never names an alternative tool or states a when-not condition, so routing versus siblings like get_client_profile or get_household_financial_snapshot is left 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?

Beyond the readOnly/idempotent annotations, it discloses the access-control model, the two projection modes and their precondition logic (resume needs the exact open obligationId; closed result derives the sole exact completed obligation and requires three converging conditions), operator exclusions, and an important caveat that neither projection proves settlement or money movement.

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

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

Front-loaded with the core action and result fields before the projection detail. The projection sentences are dense and jargon-heavy, but for a tool with two special modes and an access model, each clause carries load and nothing is pure filler.

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

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

With no output schema, the description itself enumerates the returned content and flags the projection caveats. For a 4-parameter read tool with an access model and two opt-in modes, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conditional semantics the schema only hints at: which projection requires obligationId, which accepts none, and that the projection path is external-connector only. That is real added meaning over the property 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+resource ('Get full detail of a single coordination thread') and enumerates the payload (subject, messages, attachments, participants, next owner, closeout state), which cleanly separates it from summarize_coordination_thread, list_my_coordination_threads, and find_coordination_threads.

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 scopes who may use it (household member or active participant/watcher) and who is excluded (managed-program operators, scoped specialists), plus the conditions under which each projection applies. It stops short of explicitly routing to summarize_coordination_thread for a lighter read, so it is clear context rather than full when/when-not 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it is access-scoped to self or an accessible client/member, and explicitly notes that scoped specialists are excluded unless a future permission grants the surface. Return format is not described, keeping it short of 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?

Two dense sentences with no filler. The returned contents are front-loaded, followed by the access scope and the exclusion caveat.

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

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

With no output schema, the description must carry the return surface, and it does list the artifacts returned. Combined with rich read-only annotations and a fully documented single parameter, an agent has enough to invoke it correctly; only finer output detail is absent.

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

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

Schema coverage is 100% and the single clientId parameter is documented in-schema, so the baseline is 3. The description adds meaning by clarifying that the parameter optionally targets a client/member 'you can access' while omitting it yields your own context, which the schema does not state.

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 (Get) and resource (family office context) and enumerates the concrete contents it returns: constitution, crest, mission, mode-of-operation, meeting playbook. This clearly separates it from the adjacent graph/context siblings such as get_business_entity_graph_context and get_professional_graph_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?

It gives scope ('for yourself or a client/member you can access') and an access caveat about scoped specialists, which implies when it is callable. However, it never names an alternative tool or states a when-not condition, so usage is only implied.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world. The description adds real context beyond that: it is a "latest saved" precomputed snapshot rather than a live calculation, and it discloses an authorization boundary (scoped specialists are blocked). It does not describe freshness/staleness behavior or return format, keeping it 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?

Three tight sentences: what it returns first, when to use it second, access constraint last. Front-loaded and every sentence earns its place with no filler.

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

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

For a read-only, fully-annotated tool, the description covers purpose, trigger conditions, returned fields, and an access restriction. No output schema exists but the description enumerates the payload, and the single optional parameter is fully 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?

Schema description coverage is 100% with a single clientId parameter, so the schema carries the semantics. The description adds no parameter-level meaning (it never mentions clientId or scoping behavior), so 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?

States a specific verb ("Read") and resource ("household's latest saved financial snapshot") and enumerates the exact metrics returned: cash runway, debt payoff horizon, freedom delta, calculation date, and data quality. This distinguishes it clearly from siblings like get_client_liquidity or get_client_tax_reserve.

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

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

Gives explicit trigger conditions ("how long their money lasts or how their income, spending, and debt compare") plus an access constraint ("Scoped specialists cannot access this snapshot"). It does not name specific alternative tools, so it stops short of a 5.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world semantics, so the bar is low; the description still adds real value beyond them by disclosing the 20-item result cap, the exact fields returned, and an access restriction (scoped specialists cannot read household strategies). It omits what happens when more than 20 strategies exist and whether the status filter accepts arbitrary strings.

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 tight sentences, front-loaded with the payload and bound, followed by the trigger and the negative scope. Nothing is redundant with the title or the schema, and 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?

With no output schema, the description carries the return-value burden and does so by enumerating the returned fields and the 20-item cap. The remaining gap is pagination/truncation behavior and how the status filter values map to records, which an agent may need for correct invocation.

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

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

Schema description coverage is 100%, so both parameters (status, clientId) are already documented, and the description adds nothing about their accepted values, format, or interaction. Baseline 3 applies when the schema carries the full parameter burden.

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?

Names a specific verb (read), a bounded resource (up to 20 saved household financial strategies) and the exact payload fields returned (status, next steps, progress, update dates). It also positively distinguishes itself from the sibling get_household_financial_snapshot by framing this as the strategy list rather than a snapshot, and explicitly disclaims creation/advice.

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

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

Gives a clear triggering condition ('Use when the user asks which strategies are active or what remains to do') plus explicit exclusions (not create a strategy, not new investment advice, not available to scoped specialists). It never names an alternative sibling tool to use instead, so routing between this and the snapshot/context tools still requires inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine extra context: it does not move money, make tax/legal recommendations, or treat missing evidence as an all-clear, and scoped specialists are excluded. Those boundaries materially shape how an agent should interpret and act on the result.

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 front-loaded sentences with no filler; the scope, the joined data shape, and the limitations are all stated compactly. Phrasing like 'bounded next moves' is jargon-heavy but still compact.

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

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

With no output schema, the description carries the return-shape burden and does so by enumerating what the view joins (coming dates, source records, responsible entities, connected cash, verification gaps, next moves). Combined with annotation-covered safety and full parameter documentation, an agent has enough to call this correctly, though the response format itself remains unspecified.

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

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

Schema coverage is 100% and the single clientId parameter is fully documented in the schema, including the omit-for-self behavior. The description's 'your own record or an assigned client' mirrors the schema without adding syntax or format detail, 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?

States a specific verb (get) and a specific artifact (a deterministic 90-day household readiness view), plus the scope (own record or assigned client). It clearly implies a distinct role next to snapshot/context siblings, though it never names an alternative tool to differentiate explicitly.

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 establishes the applicable scope ('your own record or an assigned client') and excludes scoped specialists, but it gives no explicit trigger for choosing this over get_household_financial_snapshot, get_what_matters_now, or get_meeting_prep. Usage is implied rather than directed.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds substantial behavioral context beyond them: exclusions and endorsements are NOT extracted, data is read from uploaded declarations, the resolved household must not be attributed to another person, and scoped specialists are excluded without an explicit future permission.

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 what the tool returns, then the guardrails. The adequacy prohibition is stated twice (once abstractly, once as a six-adjective list) and the clientId rule is duplicated from the schema, so it is somewhat longer than strictly necessary, though most sentences carry distinct information.

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

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

No output schema exists, so the description must carry the return shape, and it does so thoroughly (per-policy-type fields, staleness, currency, resolved household naming). For a single optional-parameter read tool with rich annotations, 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?

Schema description coverage is 100% for the single clientId parameter, so the baseline is 3. The description does add the decision logic (professional's own household vs. a client's) which reinforces rather than merely repeats the schema, but it does not extend beyond what the schema text already says.

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 ('Get the household insurance record') and enumerates exactly what is returned: life policies with sourced death benefit, face amount, cash value, coverage by type, staleness, plus auto/homeowners/umbrella limits, deductibles, named insured, dates, premium, currency. This is clearly distinguishable from siblings like get_household_financial_snapshot or get_client_product_state.

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

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

Explicitly states the boundary of use ('never determines coverage adequacy') and routes the excluded judgment to a named alternative (coverageReviewPolicy.requiredStatement) and a licensed professional. It also spells out the clientId condition: pass for a client unless X1 already supplied client-scoped context, omit to read one's own household.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the payload composition and the 'you can access' access-boundary hint, but says nothing about response size, latency, truncation, or partial-availability behavior for a large aggregate bundle.

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 verb and the bundle contents; the second sentence earns its place by carving out scoped specialists. The content enumeration is long but each item is load-bearing for telling an agent what it will receive.

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

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

With annotations covering the safety profile and only one fully-documented optional parameter, the remaining burden is explaining what the aggregate returns, and the description does that by listing every constituent data source. No output schema exists, but the enumeration effectively substitutes for one.

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

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

Schema coverage is 100% with a single optional clientId documented as 'Client or member user ID,' which sets the baseline at 3. The description goes beyond that by clarifying the omitted-parameter case ('a meeting with yourself') and by tying the ID to 'a client/member you can access,' adding the access-scoping nuance the schema does not express.

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 lead verb 'Bundle' plus the enumerated contents (profile, product state, Pulse, plays, documents, family-office context, activity, shared member intelligence, CRM context) state a specific resource and scope, so an agent knows this is a composite prep payload rather than a single-entity getter. The closing note about scoped specialists being excluded further differentiates it from narrower siblings like get_family_office_context or get_client_product_state. It stops short of naming which sibling to use instead, which keeps it out of the top band.

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?

'For a meeting with yourself or a client/member you can access' implies the usage context (pre-meeting aggregation) but never states when to prefer this over the individual getters it bundles or over draft_meeting_brief. Among 46 siblings, no alternative is named and no prerequisite or exclusion is given beyond 'scoped specialists are excluded,' which is a content note rather than tool routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the bar is lower; the description adds real context beyond them by disclosing the per-artifact visibility semantics and that inline content is "bounded" and only readable for "your own or member-visible" artifacts, which implies an access restriction.

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 dense, front-loaded sentences with no filler; the return-shape summary comes first and the parameter guidance last. It is information-rich rather than padded, though the middle sentence packs several distinct concepts together.

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

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

With no output schema, the description sensibly describes the key returned fields, and with zero schema coverage it documents most parameters, so an agent has enough to call it correctly. Minor gaps remain around limit/pagination behavior.

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

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

Schema coverage is 0%, so the description must carry the load, and it does for three of four parameters: clientRef (name or email), clientId, and includeContent (bounded inline content for note/markdown/html artifacts). Only limit is left unexplained (no default or pagination meaning), which keeps it short of a 5.

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 (List) and resource (professional artifacts saved to a member's X1 account) and enumerates the salient returned fields (visibility state, reviewUrl, promotedDocumentId). It is clearly distinct from document-search siblings, though it never names an alternative tool explicitly.

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?

"Use this to read back a just-saved draft and its promotion state" gives a concrete when-to-use scenario, which is more than implied usage. However it offers no exclusions or pointers to siblings such as get_vault_documents or search_my_documents for broader retrieval.

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 the safe read profile (readOnlyHint, idempotentHint, non-destructive), so the description needn't repeat that. Instead it adds genuinely useful behavioral disclosure: which sensitive fields are suppressed (arguments, signatures, authorization revisions, bearer ids) and that the disposition projection is content-free and never returns targets, records, review text, or committed results.

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 dense sentences, front-loaded with the core action and its suppression guarantees before introducing the projection variant. It is information-rich rather than padded, though the second sentence is somewhat run-on.

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

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

With no output schema and no annotation coverage of the return shape, the description does explain the two response modes (legacy default vs content-free disposition), which is valuable. But it leaves the limit and toolName parameters unexplained, so an agent cannot fully construct a correct call from this text alone.

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 0%, so the description carries the full burden. It explains requestId ('one exact requestId') and projection ('projection=disposition_v1') but says nothing about limit or toolName, leaving half the parameters undocumented anywhere.

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 (List) and resource (action-request statuses) with a clear scope restriction: 'created by this authenticated connector'. It distinguishes itself from receipt/thread siblings implicitly, but never names an alternative tool, so it stops short of full differentiation.

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 a concrete conditional for opting into the alternate response mode ('one exact requestId plus projection=disposition_v1'), which is real usage guidance. However it offers no when-to-use vs when-not guidance relative to siblings like list_my_confirmation_receipts or get_coordination_thread, so the routing value is only partial.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description adds genuinely useful context beyond that — member-entered provenance, not lender-verified, private scope, and the caveat that business balances are not a personal guarantee or household net worth.

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 compact sentences, front-loaded with the resource and contents, then provenance, then the usage caution. Dense but each clause carries information; no filler.

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

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

For a no-parameter, read-only tool with no output schema, the description supplies the provenance, scope, and caveats an agent needs to interpret the data correctly and to avoid overstating it (e.g., treating business balances as net worth). Return shape is unaddressed but that is minor here.

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

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

The tool takes zero parameters, which is the baseline-4 case; there are no parameters whose semantics need explaining and the schema is empty.

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

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

States a clear verb ("Read") and a specific resource ("your own member-entered loans") plus an enumerated inventory of contents (borrower links, dated balances, payment/maturity terms). It distinguishes the data's provenance ("member-entered", "not lender verified", "private to you"), though it never names a sibling tool to contrast against.

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?

Implied usage is present — read this before "proposing a change" and reuse the exact ids and revisions — but there is no explicit when-to-use versus alternatives or when-not-to-use guidance against the many sibling getters.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-annotation context: an explicit privacy boundary about what is never surfaced (broad advisor roster, full household record). It does not, however, disclose error behaviors such as the access-denied case that the schema hints at.

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 read action and closed by the scoping boundary; every clause carries information. The enumerated list is dense but each item earns its place. No padding or boilerplate.

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

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

With no output schema, the description is not obligated to explain return values, and annotations cover the safety profile. But for a 3-parameter listing tool it omits how limit caps results and what includeClosed toggles, and gives no hint of the access-denied failure mode, leaving gaps an agent would hit when invoking 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?

Only clientId carries a schema description (33% coverage); limit and includeClosed are entirely undocumented in both schema and description. The description adds no parameter meaning at all – no mention of pagination limits or what includeClosed changes – so it fails to compensate for the coverage gap.

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 gives a specific verb ("Read") plus a well-scoped resource (the connected network professional's shared-work context) and enumerates exactly what it returns: participant-scoped threads, packet/bundle shares, approved intro requests, and document-share boundaries. The closing negative clause ("never exposes a broad advisor roster or full household record") implicitly distinguishes it from roster/graph siblings like get_professional_graph_context, though it never names an alternative directly.

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

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

Usage is only implied: an agent can infer this is the tool for viewing shared-work context, and the exclusion clause hints at when it is the wrong tool. However there is no explicit when-to-use vs. when-not statement, no named alternative among the many sibling getters, and no mention of prerequisites such as the clientId visibility 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful context: the result is 'bounded', it merges stored claims with a 'live' team graph, and access is scoped to what the caller may see. It still omits how reviewFilter/includeEvidence alter the result.

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

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

A single front-loaded sentence with no filler; the key resource and payload contents come first. It is dense but not padded, though the phrase 'bounded professional-graph claims' is slightly jargon-heavy.

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

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

With no output schema and four undocumented parameters, the description should explain what is returned and how the filters behave. It names returned categories but leaves reviewFilter, includeEvidence, limit behavior and pagination unaddressed, so an agent cannot confidently parameterize the call.

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 0% across four parameters, so the description must carry the burden. It partially covers limit ('bounded') and clientId ('client/member you can access'), but says nothing about reviewFilter's all/confirmed_only/pending_only semantics or what includeEvidence toggles.

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: returns boundedly-scoped professional-graph claims plus the live VFO team graph, naming concrete contents (relationship labels, specialties, capability summaries). However it never distinguishes itself from the nearby sibling get_business_entity_graph_context, leaving the agent to infer which graph context applies.

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?

There is no explicit when-to-use guidance and no mention of alternatives, even though get_business_entity_graph_context, get_client_profile, and get_member_artifacts all compete for similar intent. Only the implicit qualifier 'for a client/member you can access' hints at a precondition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it is a discovery tool that surfaces an 'authority contract' but explicitly does not itself grant authority, and it flags that full detail 'can be very large'. These non-obvious behavioral traits are useful to the agent.

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 tight sentences, front-loaded with the primary purpose before the write-contract and detail guidance. Each sentence carries distinct information with no redundancy. It is appropriately sized for a 3-parameter discovery tool.

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 read-only capability-discovery tool with no output schema, the definition covers scope, the write-safety entry point, and the detail trade-off. Annotations carry the safety profile and the schema fully documents parameters, so the remaining need is small. It is nearly complete, missing only explicit routing against the get_x1_context/guide siblings.

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

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

Schema coverage is 100%, so the schema already documents all three parameters, giving a baseline of 3. The description still adds real semantic value by explaining the intended sequencing: use toolName 'before a write' to obtain an execution/authority contract, and reserve detail: full for large diagnostic responses — guidance not present in the raw schema text.

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?

Starts with a specific verb+resource: 'Get a compact summary of the connected user's X1 entitlements, feature access, subscription context, and MCP scope visibility', which clearly identifies a capabilities/introspection tool. It also discloses a second mode (per-tool write contract via toolName). It does not, however, differentiate itself from siblings like get_x1_context, get_x1_guide, or get_x1_workflow_guide, so an agent must infer which introspection tool to pick.

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

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

Gives a concrete trigger condition: 'Before a write, pass toolName for that mounted write tool's complete execution and authority contract', plus 'Use detail: full only for large diagnostic responses.' This tells the agent when to use the summary mode vs the toolName mode vs full detail. It stops short of naming when-not-to-use or routing to a specific alternative sibling among the many get_* tools.

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

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

Adds substantial context beyond the readOnly/idempotent annotations: never construct a documentUrl, rate limiting, access-history logging for each release, and the role-scoped visibility model (advisors, scoped specialists, managed-program roles). None of this is derivable from the schema or annotations.

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

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

Purpose is front-loaded and each sentence carries information, but it is a dense single block that would scan better as grouped sentences (output fields vs. routing vs. permissions). Slight redundancy across the connector/X1 routing discussion.

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 no output schema, the description covers return contents (id, documentUrl, summary), the permission and rate-limit model, and role scoping. It stops short of describing pagination/limit behavior and how managed-program role metadata differs, but is otherwise complete.

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

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

Schema coverage is 100%, so documentId/limit/category/clientId are already documented. The description adds meaning only to the output fields (id, documentUrl, summary) and clarifies documentId can poll indexing state, but not parameter syntax. Baseline 3 applies.

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

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

States a specific verb+resource ('Canonical MCP read for vault document inventory') and immediately distinguishes itself from search_documents and the per-document tools. An agent can tell what this returns (a document list with ids) without opening the schema.

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

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

Explicitly routes the agent: use get_document_content / get_document_download_url on external connectors once per document id when mounted, otherwise open in X1. It also cites prerequisites (download permission, connected-document access), so when-to-use and when-not are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is lower. The description adds genuine behavioral context beyond annotations: the composition of results (focus items + grounding context + suggested next actions) and a permissions/scoping constraint about specialists being excluded. Good value added.

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 compact sentences with the primary purpose front-loaded and a caveat second. No filler, though the second sentence's phrasing is slightly abstract.

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 read-only, zero-required-param tool with 100% schema coverage, the description is nearly complete. It omits any notion of result shape or ordering, but with no output schema and readOnly annotations, the remaining gap is minor.

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

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

Schema coverage is 100% and both parameters (clientId, weekStart) are well documented with omit-defaults semantics. The description adds no parameter detail beyond the schema, so 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?

States a specific verb ('surface') and resource ('prioritised weekly focus items with grounding context and suggested next actions'), which clearly distinguishes it from sibling getters like get_meeting_prep or get_my_action_requests. It's clear what the tool returns, though the 'member's' scope vs 'own household' isn't fully differentiated from relatives like get_client_activity.

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?

No explicit when-to-use guidance relative to siblings such as get_my_action_requests or get_meeting_prep, which likely overlap. The sentence about scoped specialists is a permission caveat, not usage selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds that the payload contains 'product context, surfaces, and MCP guidance', but does not clarify what 'surfaces' means, how large the response is, or whether it is static content versus live state.

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

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

A single front-loaded sentence with the action first and the rationale second; nothing is wasted. It is slightly padded by the trailing 'how it is meant to be used' clause, which adds little beyond the preceding phrase.

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 context tool with no output schema, the description gives a rough sense of the payload but not its structure or when it beats the sibling guide tools. An agent can invoke it correctly but may not know it picked the right X1-related 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly does not invent parameter behavior.

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 ('Get structured X1 product context, surfaces, and MCP guidance') and scopes it to orientation about the X1 product, which is more concrete than the bare name. However, it never distinguishes itself from close siblings like get_x1_guide and get_x1_workflow_guide, so the agent cannot tell which of the three to call.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named despite two obvious sibling candidates (get_x1_guide, get_x1_workflow_guide). The clause 'so Claude can reason about what X1 is' hints at intent but leaves routing entirely to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds that the guide is curated, account-specific ('describes their own account'), and covers boundaries and workflows, which tells the agent the content is personalized rather than generic. It does not describe return format or pagination, but with rich annotations this is a solid addition.

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

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

A single front-loaded sentence that begins with the usage trigger and then lists the guide's contents. There is no wasted language, and the key routing condition is placed 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?

With four optional parameters, full schema coverage, and no output schema, the description supplies the missing content-level context: it explains that the tool returns an account-specific guide covering X1, capabilities, workflows, and boundaries. It omits explicit routing against similar siblings, but is otherwise complete enough for correct invocation.

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

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

Schema coverage is 100%, so all four optional parameters are already documented with descriptions, enums, and examples such as 'what can X1 do for me'. The description adds no parameter-level syntax or semantics beyond what the schema provides, making the baseline 3 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?

States a specific resource (a curated guide to X1) and scope (what this person can do on this connection, key workflows, boundaries) in concrete terms. It does not explicitly differentiate from sibling tools like get_x1_workflow_guide, which also likely covers workflows, so it falls short of a 5.

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

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

Explicitly says 'Use when the connected person asks what X1 is or what X1 can do for them,' giving a clear trigger condition. It does not name when not to use it or point to alternatives such as get_x1_context or get_x1_workflow_guide, so it stops short of the top 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds only that it returns 'full production app URLs' and is 'role-aware', but does not disclose what the guidance contains, length, or limitations. With annotations covering safety, the bar is lower, but this still adds little beyond the schema.

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

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

The description is a single sprawling sentence that crams two purposes and a long list of workflow artifacts without structure or front-loading. It is difficult to parse and violates conciseness principles.

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 4 parameters, two enums, read-only annotations, and no output schema, the description should clarify the relationship between workflow selection and guidance topics, and what the output entails. It omits output format entirely and conflates two distinct functions, leaving the agent unsure of expected 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?

Schema description coverage is 100%, so each parameter already has a description. The description adds 'role-aware' context and mentions full production app URLs, but does not explain parameter interactions or defaults beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description lists topics and workflow artifacts but the core purpose is buried in a dense run-on sentence. It reads as a catalog rather than a clear statement of what the tool does, and it is hard to distinguish from siblings like get_x1_guide or get_what_matters_now.

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 enum parameter description provides conditional guidance (e.g., 'Use financial_workbench for broad financial questions', 'Use review_capital_call only for a capital-call notice'), which implies when to use certain workflows. However, the top-level description offers no explicit when-to-use guidance or alternatives to this guide tool itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds behavior they cannot: the default page size of 20, the distinction between memberCount (total matches) and returnedCount (this page), the response-size budget that can shorten a page, and the requirement to reuse the same query when paging. With no output schema, this is exactly the disclosure an agent needs.

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

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

Four dense sentences, front-loaded with the lookup purpose, then return shape, then pagination, then the ambiguity warning. Every sentence carries weight, with only minor overlap against the schema's own cursor/limit 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 zero-required-param, read-only paginated search with no output schema, the description covers defaults, paging, returned fields (role, profile policy, specialist boundaries), and multi-match ambiguity. It omits any note on authorization requirements or what 'managed-program/VFO' means, but nothing essential to 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 limit, query, and cursor are already fully documented. The description restates the default-20 and same-query-for-cursor semantics but adds no new syntax or constraints beyond the schema, matching the baseline 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?

States a specific verb (find/list) and resource (authorized managed-program or VFO members) plus the lookup keys (name, email, exact ID). The 'authorized managed-program or VFO' scope distinguishes it from the many document/thread/entity siblings, though no sibling is named explicitly to route between near-neighbors.

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 clear context: prefer search when a person is named, never guess between multiple matches, and only follow nextCursor when more results are needed. It stops short of naming an alternative tool or stating when not to use it, but the conditions for use are unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the 'writes nothing' sentence is partly redundant — but 'grants no document access' and the caller-eligibility rules (member vs professional vs scoped specialist) are behavioral facts the annotations do not encode. It still omits pagination/limit 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?

Three dense sentences, front-loaded with purpose before eligibility constraints; little waste. The middle 'Read-only' sentence slightly overlaps the annotations and could be trimmed.

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

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

An output schema exists so return fields need not be explained, yet the description still lists them usefully, and it covers the authorization model thoroughly. The gaps are the undocumented limit/pagination semantics and the unstated default for status.

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 0%, so the description must carry the param burden. It explains clientId well (omission rules per role) and mentions status values, but it silently drops the schema's 'all' enum value and says nothing about what limit does or what the default status is. Baseline 3 for partial compensation.

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

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

States a specific verb and resource ('List the document requests on an X1 record') and enumerates exactly what each listed item contains (status, type, reason, deadline, requester, timestamps). This clearly separates it from the write-side sibling draft_document_request and from search_documents or get_vault_documents.

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, role-conditional access rules: members may omit clientId, professionals must pass clientId unless X1 supplied a client-scoped context, and scoped specialists are excluded. That is genuine when-to-use/when-not guidance rather than implied usage.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavioral context beyond them: self-added items are labeled, non-source-backed, and non-fileable until X1 matches evidence; explicit current filters stay source-backed; non-fileable entities can't be belongs-to targets; identifiedForReview items are never counted. This is rich, non-redundant disclosure.

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 purpose is front-loaded, but the body is a single dense paragraph mixing return contents, filter behavior, filing eligibility, and role permissions. Each clause is substantive but the lack of structure makes it harder to parse than it needs to be.

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

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

With no output schema and six parameters at 50% description coverage, the description does most of the heavy lifting: it explains the filtered-return behavior, the identifiedForReview bucket, and filing constraints. Only a few parameter-level details remain underspecified.

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 50%: status, clientId, and clientRef are documented in-schema. The description adds meaning for includeCounts ('optional document/artifact counts') and implies entity types and lifecycle state, but limit, the entityType enum values, and includeCounts semantics are not explained beyond the schema. It only partially compensates for the coverage gap.

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: 'List the household's structured entities, trusts, properties, assets, and personal filing bucket,' and enumerates the returned fields (stable IDs, lifecycle state, aliases, counts). This clearly distinguishes it as a household-graph listing tool, though it doesn't explicitly contrast with nearby siblings like get_household_financial_snapshot or get_family_office_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?

It gives concrete usage context: members and Multiplier operators use fileable IDs for filing/cleanup, advisors use them to understand the household map and file artifacts, and scoped specialists are excluded. However, it never explicitly routes the agent away from this tool to a specific alternative when the household graph isn't what's wanted.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's added value is the role-based visibility scoping and the fact that results are split into two lists. It stops short of describing pagination behavior despite a limit parameter.

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 tightly packed sentences with the primary output stated first and the role-scoping caveat second; no filler. The second sentence is dense and slightly run-on, but every clause carries information.

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

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

There is no output schema, and the description compensates by explaining the two-list return structure and the role-dependent filtering. It leaves the limit/pagination behavior and empty-result handling unspecified, which is a modest gap for a read-only 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 description coverage is 75%, with status, clientId, and clientRef already documented in-schema, including the 'Defaults to pending' and 'Members usually omit this' notes. The description adds no syntax or format detail beyond what the schema 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 gives a precise verb+resource ('List ... household entity cleanup proposals for a member') and immediately clarifies the return shape by naming a second distinct output list, ownershipEdgeProposals. That resource is clearly separable from the closest sibling, list_household_entities, which returns entities rather than proposals.

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 spells out role-conditional behavior: members/coaches/admins get the actionable review queue, while advisors and scoped professionals see only their own submissions. That tells an agent what to expect for the calling user, but it never states when to prefer this tool over an alternative or what to do if the result is empty.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the crucial behavioral traits: receipts are single-use, viewing one confers no authority, and X1 re-verifies signature, surface, tool, live entitlements, and exact arguments before execution. That is exactly the kind of safety semantics an agent needs and cannot infer from the annotation block.

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

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

Three sentences, front-loaded with the core action and scope before the usage cue and the safety caveat. Every clause carries distinct information; nothing is redundant padding.

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

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

With no output schema, the description still communicates what is returned (unused receipts on this surface) and why it matters, and the two optional parameters are covered by the schema. Minor gaps remain around ordering or how the limit interacts with the result set, but nothing essential is missing.

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

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

Schema description coverage is 100%, so limit and toolName are already fully documented in the schema. The description adds no syntax, default, or format detail for either parameter, so the baseline 3 applies.

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

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

States a specific verb (List) plus a precisely scoped resource (confirmation receipts you granted in X1 that have not been used yet, on this connection's surface). The scoping qualifiers cleanly distinguish it from siblings like get_my_action_requests or list_household_entity_change_proposals without needing to open 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 an explicit trigger: 'Use it after someone approves a batch of queued proposals in X1 so you can act on exactly what they approved.' That is clear when-to-use guidance, but it names no alternative tool or when-not condition, so it stops short of a full routing statement.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-schema context: the caller-relative visibility model ('members see their own; professionals only see threads where they are active participants or watchers') and the shape of each returned row.

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 front-loaded sentences: purpose and returned fields first, then usage guidance, then visibility. Efficient, though the attention explanation slightly duplicates the schema description rather than adding new information.

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

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

With no output schema, the description usefully enumerates returned fields (status, next owner, last activity, attention signals, summary) and explains the access model. Gaps remain around pagination/limit behavior and the status enum, but the core calling context is present for a read-only listing tool.

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

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

Schema description coverage is 40%: clientId and attention are documented in the schema, while limit, status, and includeClosed are undocumented in both places. The description's attention guidance largely restates the schema's own attention description and says nothing about limit, includeClosed, or what the status enum values mean, so it only partially compensates.

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?

Clear verb+resource ('List coordination threads') with an explicit access scope ('the caller can access') and an enumeration of returned fields. However, it never distinguishes itself from the sibling find_coordination_threads, which an agent could plausibly confuse it with.

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

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

Gives concrete when-to-use guidance for the attention modes ('use waiting_on_me for what is on my plate', 'changed_since_last_read for what changed since I last looked'), and states the visibility rule for members vs professionals. It stops short of naming an alternative tool or stating when NOT to use this one.

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 readOnly/idempotent annotations, it discloses asynchronous indexing lag, the 'still indexing, try again shortly' response pattern, that results carry a document id and an X1-authored documentUrl, a firm prohibition on constructing URLs, rate limiting, current-download-permission and household-access requirements, and access-history recording.

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

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

Purpose is front-loaded and every sentence carries operational information rather than filler; length is justified by the connector, permission, and indexing caveats. It is dense and slightly long, but no sentence is redundant.

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

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

With no output schema, the description compensates by describing the result shape (document id, optional documentUrl), indexing behavior, permission prerequisites, and the per-role visibility model — everything an agent needs to call and interpret this tool.

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

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

Schema coverage is 100%, so the schema carries the baseline, but the description adds real query semantics the schema lacks: filename matching works as displayed in Vault even when the stored name uses separators, and it clarifies that the returned documentUrl must be used verbatim. The category/clientId/dateFrom filters get no extra elaboration.

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

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

The opening sentence gives a specific verb and resource with scope: 'Canonical MCP read for vault document metadata and summary search.' It implicitly separates this tool from the body-content variants by directing content queries elsewhere, though it never names search_my_documents or search_my_document_contents explicitly, so an agent must infer the sibling boundary.

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 routes the agent: metadata/summary search here, 'use the body-content search tools for content', then on external connectors use get_document_content or get_document_download_url per document id, otherwise open in X1. It even covers role-scoped visibility for advisors, specialists, and managed-program roles.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely new behavioral context: rate-limit handling ('wait for outstanding searches and retry one at a time'), asynchronous indexing with a 'still-indexing' state, and the fact it returns passages rather than writing an answer. This meaningfully exceeds the annotation set.

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

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

Purpose and scope are front-loaded, and nearly every sentence carries routing or behavior information. It is dense with parentheticals and could shed a clause or two, but there is little pure 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?

An output schema exists, so return values need not be re-explained. The description still covers the tricky edges an agent needs: coverage semantics, asynchronous indexing, rate limiting, and the governed retrieval contract. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains the coverage enum trade-off, that documentIds allow up to 10 comparison targets in one request, and that 'IDs never grant access.' Only 'limit' is left entirely to the schema.

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

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

States a specific verb and resource: 'Search the text (body contents) of the connected person's own documents in X1,' with examples (trusts, policies, agreements, K-1s). It also explicitly distinguishes itself from the metadata/name search sibling, so an agent can route without opening a schema.

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

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

Gives explicit when ('when they ask what their own documents say'), a named alternative for a different axis ('to search by document name, title, or tag instead, use the document metadata search'), and a scoping trigger for documentIds ('to compare known files'). When/when-not/alternatives are all 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?

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds real value: the server binds the search to the authenticated account and accepts no clientId/account identifier, only X1-authored documentUrl links should be used, and an empty result means no matching metadata rather than a missing notice. That is substantive behavioral context 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?

Front-loaded with the core action, then progressively adds scoping, routing, and result-handling rules. It is longer than most definitions but nearly every sentence carries distinct operational guidance; only the closing sentence about the governed metadata audit and document authority feels like boilerplate.

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

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

With no output schema, the description compensates by describing the return shape (X1-authored documentUrl links, use only those) and the meaning of an empty result. Combined with the account-binding rule and sibling routing, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so query, category, and dateFrom are already documented, establishing the baseline of 3. The description's mention of 'filename, title, and tags' as searchable facets is only loosely mapped onto the actual parameters (there is no tag parameter), so it adds flavor but little precision.

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) and resource (your own X1 Vault) plus the searchable facets (filename, title, category, tags) and the pre-indexing scope. It clearly differentiates itself from siblings search_documents and search_my_document_contents by naming the vault ownership boundary.

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

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

Explicitly says when to use it (the connected person searching their own Vault, even if they hold an admin or professional role) and routes alternatives: search_documents for a client's Vault, search_my_document_contents for cited body passages. Exclusions and alternatives are stated, not implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is largely covered. The description reinforces this with domain-specific detail (no Vault import, no browser launch, no external contact), which adds some concrete value but mostly restates the annotation surface.

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 tight sentences with the purpose front-loaded and the safety constraints as a clear follow-up. Nothing is wasted.

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

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

There is no output schema, so the description should convey the return content; it hints at 'artifacts and proposed filings' but doesn't describe the summary's shape or what happens when the mission has no artifacts. Adequate for a read-only tool but leaves return expectations underspecified.

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 0% for the single required parameter (missionId), and the description never mentions it or its expected format. With a parameter present and undocumented, the description should compensate but does not.

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

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

States a specific verb ('Summarize') and resource ('quarantined BrowserMission artifacts and proposed filings'), which is distinct from siblings like get_browser_mission_status and draft_browser_evidence_mission. It does not explicitly name the adjacent tools, so an agent must infer the boundary, but the resource specificity is high.

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 'for member review' implies the use context, and the read-only disclaimer signals when the tool is appropriate. However, it never states when to prefer it over siblings such as get_browser_mission_status, nor any exclusions or 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value by disclosing the briefing's actual contents (participants, status, decisions, open questions, next step) and, notably, that the delta is 'caller-specific' and relative to last look — context an agent cannot derive from the annotations.

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

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

Two tight sentences with the core purpose front-loaded and the content enumeration second. No filler, though the long comma-separated list slightly blurs into the delta clause.

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

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

With no output schema, the description correctly carries the burden of describing the return shape by enumerating the briefing's sections. Combined with access rules and the caller-specific delta note, it is sufficiently complete for a read-only summarization tool, though focus-value behavior remains unstated.

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 only 33% and the description lists content categories (next step, decisions, open questions, delta) that map onto the focus enum values, partially compensating for the low coverage. But it never explains the focus enum itself or the difference between 'full' and the narrower focuses, leaving the parameter only loosely clarified.

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?

Specifies a clear verb (summarize/generate a briefing) and resource (coordination thread), and the word 'briefing' implicitly contrasts with fetching a raw thread via get_coordination_thread. However, it never names the sibling alternatives (get_coordination_thread, list_my_coordination_threads) explicitly, so the differentiation is inferred rather than 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?

It states visibility/access conditions ('visible to the household member or an active participant/watcher') and notes that professional callers are limited to threads where they participate, but gives no explicit when-to-use-this-vs-get_coordination_thread guidance. Usage is implied by the noun 'briefing' rather than spelled out.

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