Antevo Mandates

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

The description discloses traits the annotations don't: the upsert semantics ('a member already assigned gets the new role'), the consequential side effect that assigning PRIMARY replaces the current primary, and the required permission level. That is exactly the extra context an agent needs before a non-destructive but state-changing call.

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 clauses, front-loaded with the core action and each carrying a distinct fact (roles, upsert, primary replacement, permission). No filler or repetition.

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

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

An output schema exists, so return values needn't be explained, and permissions and mutation side effects are covered. The only gap is the undocumented firm_id parameter and the lack of guidance on where to obtain member IDs.

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 compensate. It defines the meaning and allowed values of the role parameter, but says nothing about firm_id (which has a default of empty and is ambiguous), nor what client_id/member_id must reference. 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 uses a specific verb+resource ('Assign a firm member to a client') and enumerates the three valid roles, so the action is unambiguous. It doesn't explicitly contrast with siblings like get_client_team, but no sibling overlaps enough to create confusion.

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 the prerequisite ('Needs the OWNER or ADMIN role in the firm') and implies when to use it (adding/adjusting a client's team), but it never names alternatives or exclusions. An agent gets context but no routing guidance against related 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?

The description discloses the key mutation effects beyond the annotations: it sets the last review to now, computes the next review date from next_review_months, and saves notes as an internal note. This is useful behavioral context even though annotations already indicate the operation is non-read-only and non-destructive.

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

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

The description is compact and front-loaded with the core action. Every clause adds useful information about dates or notes, with no redundant framing.

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

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

Given the output schema and annotations, the description covers the main behavior an agent needs to call the tool correctly. The main gap is that firm_id is not mentioned, but the core review-completion semantics are otherwise well specified.

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 0% schema description coverage, the description must compensate. It usefully explains next_review_months (default 12, range 1 to 120) and notes behavior, but it does not explain client_id or firm_id, leaving some parameter semantics to inference.

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: recording that a client's review is done. It also specifies the resulting date updates and note side effect, making the action clear. However, it does not explicitly differentiate this from sibling tools such as get_client_reviews_due.

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 intended use is implied by 'Record that a client's review is done,' so an agent can infer it should be called after completing a review. There is no explicit guidance on when not to use it or which alternative tools to consider.

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 flag destructiveHint=true and idempotentHint=true, so the bar is lower, but the description still adds real context: the two-phase plan/confirm flow and what the no-op behavior looks like for already-converted clients. It doesn't say whether the operation is reversible or what confirmation actually commits.

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?

Roughly four sentences, front-loaded with the outcome and then layering defaults, idempotency, and the confirm gate. No redundant restatement of the tool name or title.

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 needn't be described, and the plan-first flow plus idempotent behavior covers the main unknowns for a destructive write. The unexplained firm_id and the lack of any permission/authorization notes keep it from being fully 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 0%, so the description carries the burden and does so for the tricky parameters: entity_type's allowed values (PERSON, COMPANY, TRUST, FOUNDATION) and its default derivation from client type, household_name's default, and confirm's role. firm_id is left entirely unexplained.

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+resource ('Convert a prospect into an active client') and enumerates the concrete side effects: household creation, primary entity creation, and status set to ACTIVE. That makes the tool distinct from pure setters like update_eam_client, though it doesn't explicitly contrast itself with the nearby create_eam_client sibling.

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 the operational pattern explicitly: 'Needs confirm=true: the first call returns a plan.' It also explains the idempotent edge case ('A client already converted is returned as it is'). It stops short of saying when to prefer this over create_eam_client.

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 write, non-idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the goal is created with status ON_TRACK, a server-side default the agent could not otherwise predict. It omits any duplicate-handling or validation-failure behavior, keeping it below 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, front-loaded with the core action and initial state, then the constraint details. Every clause carries information; the enumeration of enum values is compact rather than padded. Slightly telegraphic but not wasteful.

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 explained, and annotations cover the mutation profile. But for a 9-parameter creation tool with zero schema description coverage, the description leaves major inputs (target_amount, target_currency, firm_id) unexplained and says nothing about the required client_id or validation behavior — an agent could call this and omit the amount entirely.

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 burden and does partially compensate: it enumerates all eight goal_type values, gives the target_date format (YYYY-MM-DD), and explains priority ordering (1 is highest). However, six of nine parameters — client_id, firm_id, goal_name, description, target_amount, target_currency (default CHF) — get no mention at all, and target_amount is a critical field for a financial goal.

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 ('Add a financial goal for a client') plus a distinguishing behavioral detail (starts ON_TRACK), which separates it from update_client_goal and get_client_goals by implication. It never names the sibling tools explicitly, so it stops 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?

The word 'Add' implies a creation context, so usage is inferable, but there is no explicit statement of when to use this versus update_client_goal, or what preconditions exist (e.g. whether the client must already exist). Guidance is implied rather than stated.

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 only declare the generic mutating profile (readOnly=false, destructive=false, idempotent=false); the description adds genuinely new behavior — a confirm-gated two-phase write whose first call returns a plan rather than creating anything. It also discloses the ownership side effect ('assigned to you'). It doesn't say what the second call returns or what happens on duplicate names.

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 chunks, front-loaded with the action and scope, then enum lists, then the confirm requirement last. No filler, though the enum listing is dense and could be more scannable.

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

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

An output schema exists, so return values needn't be described, and the confirm flow is covered. For a mutating 8-parameter tool with zero schema coverage, the description still omits permissions/firm_id requirements, duplicate-handling, and the effect of the second call — gaps an agent would notice.

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 parameter meaning; it fills the biggest gap by enumerating allowed values for client_type (INDIVIDUAL/FAMILY/ENTITY) and pipeline_stage (LEAD/PROSPECT/NEGOTIATION/ONBOARDING), which the schema does not constrain at all, and explains confirm. It leaves firm_id, display_name, and the contact fields (email/phone/notes) undiscussed.

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 ('Add a client or prospect to your firm's book') and adds scope ('assigned to you'), which separates it from update_eam_client and convert_prospect conceptually. It does not explicitly name those siblings, so it stops 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?

The 'Needs confirm=true: the first call returns a plan' line gives concrete invocation guidance for the two-step flow, and enum values are listed. However, there is no guidance on when to choose this over convert_prospect or update_eam_client, nor any stated prerequisite such as firm membership.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), it discloses the security posture ('anyone holding the link can download'), the expiry ceiling (default 24, max 720 = 30 days), that a token and expiry are returned, and the confirm-gated first call. That is exactly the mutation/authorization context annotations don't carry. It only omits that each call mints a distinct link (non-idempotent), a small gap.

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: purpose and access model first, then expiry bounds, then the confirm requirement. Every clause carries information and nothing is repeated from the 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?

For a 4-parameter mutation with an output schema, the description covers the access model, the expiry constraint, the return contents, and the confirm workflow. An agent has everything needed to invoke it correctly on the first try.

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 parameter meaning, and it does: it documents expires_in_hours' default and hard cap and explains the confirm flag's two-phase semantics. household_id and doc_id are left implicit, but their names are self-describing within the 'household's document' framing.

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 ('Create a public download link to a household's document') and immediately clarifies the access model. No sibling tool in the list creates share links, so the boundary 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?

Gives an explicit operational prerequisite: 'Needs confirm=true: the first call returns a plan,' which tells the agent it must run a two-phase flow. It doesn't name alternatives or when-not-to-use, but no sibling offers overlapping functionality, so the gap is minor.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely new behavior: deletion is a soft mark rather than a purge, and there is a plan-then-confirm flow. It is slightly ambiguous about whether omitting confirm (default false) is what triggers the plan call.

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

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

Two short sentences, no filler, and the most important facts (soft delete, confirm requirement) are front-loaded before any elaboration.

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 explained, and the description covers the mutation semantics and confirmation gate. The only gap is the precise behavior of the first (unconfirmed) call versus an explicit confirm=false.

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 3 parameters, so the description must compensate. It fully explains the non-obvious 'confirm' parameter and its default-false plan behavior, but says nothing about doc_id or household_id beyond the surrounding sentence implying household scoping.

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 (Delete) and resource (a household's document), plus the exact outcome: the document is marked DELETED and no longer listed. That soft-delete framing distinguishes it clearly from update_document and list_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?

Explains the required two-step invocation: confirm must be true, and the first call returns a plan. It does not name alternative siblings (e.g. update_document for corrections), but for a delete tool the when-to-use is self-evident and the sequencing guidance is the critical part.

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

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

The description confirms the safety profile declared by annotations ('Nothing is queued or changed'), so there is no contradiction. It also discloses the unusual behavior that the response is guidance rather than extracted data, which is exactly the kind of trait annotations cannot express. It stops short of saying whether the call can fail or what the guidance payload 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 key constraint ('not available yet') and closed with the safety assurance. Every sentence carries information; nothing is padded.

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 spelled out, and the description still summarizes what comes back (instructions). For a deliberately stubbed tool the coverage is nearly sufficient; the missing piece is any explanation of the two required identifiers.

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?

Both parameters have 0% schema description coverage, so the description must compensate and largely does not. 'doc_id' is loosely implied by 'from the document', but 'household_id' is never mentioned at all, leaving an agent to guess what household scoping means for a call that performs no extraction.

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 plainly that extraction is not available over this connector and that the tool returns instructions for starting an extraction via the Antevo app or a REST call. The verb+resource is clear and no sibling tool covers extraction, so differentiation is inherent. It loses a point only because the name/title ('extract_document_data') still implies an extraction capability the description then walks back.

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 sets expectations: don't call this expecting data, call it to learn how to start an extraction, and it names the two viable paths (in-app or REST call). It does not explicitly say which sibling tool to use instead, but no sibling performs extraction, so the routing gap is minor.

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

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

The annotations already say readOnlyHint=false and idempotentHint=true, and the description adds the specific reason: it 'saves the client's relationship-health score for the day.' It also discloses that empty sections come back empty, which is useful behavioral detail. It doesn't cover permissions, cost, or latency, so it is not 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?

The verb and resource are front-loaded, and the long middle enumeration of brief sections is dense but purposeful. It is fairly long, yet every clause maps to a section or behavior an agent might need to know.

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 needn't explain return values, yet it does enumerate sections—useful but partially redundant. The more significant gaps are the unexplained firm_id parameter and the absence of any guidance on when to choose this tool over a sibling like get_client_dossier.

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 implies client_id via 'for one client' but never mentions firm_id, leaving one of the two parameters entirely undocumented in both schema and prose.

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

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

The description opens with a specific verb and resource ('Build a meeting brief for one client') and then enumerates the section types the brief will contain, so an agent knows exactly what the tool produces. It falls short of a 5 because it never differentiates itself from the similar-looking sibling get_client_dossier.

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?

Meeting preparation is clearly the implied context, but the description never states when to use this tool versus get_client_dossier or another retrieval tool, nor any preconditions. Usage must be inferred from the name and the enumeration of brief sections.

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, so the safety profile is covered. The phrase "as stored" usefully signals this is a raw, unenriched record, but it does not address tenant scoping via firm_id or any access constraints. Additions are modest against an already-complete 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?

Front-loaded verb and resource, then one dense enumeration of returned fields, closing with a sibling pointer. The field list is long but each item helps an agent judge relevance; no filler sentences.

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

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

An output schema exists, so return-shape explanation is not strictly required, and annotations cover safety. What remains unaddressed is the input side: the purpose and behavior of firm_id and the format expected for client_id, which an agent needs in order to invoke this 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 burden for client_id and firm_id yet never mentions either. The default-empty firm_id in particular is ambiguous (tenant scoping? optional fallback?) and the description offers no clarification, leaving the agent to guess.

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?

Specific verb (get) plus resource (client's record) with an explicit enumeration of what the record contains: profile, contact details, tier, compliance, AUM, household_id. It also pre-empts confusion with get_client_team by naming that sibling and what it holds instead.

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 clearly establishes this as the entry point for a client's stored data and routes the team question to get_client_team. It doesn't state exclusions or when a different lookup (e.g., get_eam_clients) is preferable, so it falls short of a full when/when-not 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 declare readOnly, idempotent and non-destructive, so safety needs no restating. The description adds genuine behavioral context the annotations lack: cancelled goals are filtered out and results are ordered by priority, which affects how an agent should interpret an empty or ranked list.

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 resource and scope, then lists returned fields. 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?

An output schema exists, so enumerating returned fields is not strictly needed, and annotations cover the safety profile. However, with zero schema coverage on a required client_id and an optional firm_id, the description leaves an agent without enough information to construct a correct call in multi-firm contexts.

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 both parameters. The description only implies a client identifier through the possessive 'client's' and says nothing about client_id's format or what the optional firm_id with a default of '' does — 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?

Names a specific verb ('Get') and resource ('client's financial goals'), enumerates the goal categories covered, and states the exclusion of cancelled goals plus the fields returned. It is clearly distinguishable from the create/update goal siblings by being the read path.

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 by the verb: an agent can infer this is the retrieval call when it needs a client's goals. There is no explicit statement of when to prefer it over get_client_dossier or other read siblings, and no prerequisites are given, though the 'cancelled goals excluded' note conveys scope.

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 read-only annotations, the description adds meaningful behavior: active clients only, next review date required, soonest-first ordering, a cap of 50, and negative days meaning overdue. It does not explain pagination beyond the 50-item cap or how firm_id scopes 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?

The description is a single front-loaded sentence with no wasted words. It packs filtering, ordering, limit, returned fields, and overdue semantics efficiently.

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 explained. However, the description leaves firm_id undocumented and gives no alternative-tool guidance, which is a meaningful gap for a two-parameter 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 0%, so the description must compensate. It explains client_id only partially ('for one client') and omits firm_id entirely, leaving a key parameter undocumented.

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 active clients with a next review date, soonest first. The purpose is clear and distinguishable from generic client-list siblings, though it does not explicitly name an alternative tool.

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

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

It gives one conditional usage cue: 'Pass client_id for one client.' That is useful but limited; it does not say when to use this tool versus other client-listing or review tools, or when not to use it.

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

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 adds real value beyond that with the caveat 'Names are not included', which tells the agent it will get IDs only and must resolve names elsewhere — a non-obvious behavioral constraint. It does not cover pagination or the behavior of an empty team.

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; the core action is front-loaded and the field list plus the 'names are not included' caveat follow without 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?

An output schema exists, so restating return fields is arguably optional (though the field list is a helpful summary). The significant gap is the total silence on the two input parameters, especially the ambiguous 'firm_id' default, which leaves an agent unsure how to scope 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%, so the description carries the burden, yet it says nothing about 'client_id' or 'firm_id'. The 'firm_id' parameter in particular has a default of empty string and an undocumented role (filter? scope? inferred?), which the description should clarify 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 and resource ('List the firm members assigned to a client') and then enumerates exactly which fields come back, so the agent knows precisely what this returns. It is also clearly a read operation, distinguishing it from the sibling mutator 'assign_team_member'.

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 usage is implied by the verb and resource — an agent can infer this is the way to inspect team assignments — but there is no explicit when-to-use/when-not guidance and no sibling is named (e.g., the relationship to 'assign_team_member' or 'get_client_dossier' 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful scope by stating exactly what metadata and share-link count are included, but it does not discuss permissions, rate limits, or other behavioral constraints beyond annotations.

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

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

The description is a single, front-loaded sentence with no filler. The field list is long but directly supports what the tool returns, so every part 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 simple read-only tool with an output schema already defining return values, the description is mostly adequate. However, with 0% parameter description coverage, it should do more to explain household_id and doc_id, and it lacks explicit routing relative to list_documents.

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%, and neither required parameter has a description in the schema. The description implies that doc_id identifies the document, but it does not explain household_id or clarify how the two parameters relate to the lookup.

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 ('Get one document's metadata') and enumerates the metadata fields returned. It is clearly distinguishable from list_documents and mutation siblings like update_document or delete_document, though it does not explicitly name 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 'Get one document's metadata', suggesting this is for inspecting a single document rather than listing or modifying documents. However, it gives no explicit when-to-use guidance, no exclusions, and no mention of its sibling list_documents.

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 closed-world scope, so the safety profile is covered. The description adds meaningful behavioral context beyond that: a 100-record cap, ordering by name, and the important scoping rule that members without the whole-book role see only their assigned clients.

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-load the resource and returned fields, then add visibility rules, then filtering options. Every clause carries information an agent needs and there is 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?

With annotations covering safety and an output schema covering return shape, the description supplies the remaining critical context: result cap, ordering, role-based visibility, and filter semantics. The only omission is any explanation of firm_id, which keeps it from being fully complete for a 0%-coverage 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 coverage is 0%, so the description must carry all parameter meaning. It does well for three parameters—status values (ACTIVE, ARCHIVED), pipeline_stage values (LEAD through ARCHIVED), and that search matches name and email—but leaves firm_id completely unexplained, which is a clear gap given the zero schema coverage.

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

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

The description names a specific verb (List) and resource (clients and prospects in your firm's book), plus the fields returned and the 100-record cap, so the agent knows exactly what the tool does. It stops short of naming a sibling such as get_client_dossier or get_client_goals to contrast against, so it is clear but not fully sibling-differentiated.

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

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

The description implies usage by describing the filters (status, pipeline_stage, search term) and the role-based visibility rule, which helps an agent decide when this list is appropriate. However, it never states when *not* to use it or points to a sibling like get_client_dossier for single-client detail, leaving alternative selection 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, and non-destructive behavior, so the safety profile is covered. The description adds a genuine behavioral constraint in 'you can see in your firm's synced mailboxes', implying access scoping, but says nothing about what happens for a message outside that scope or for an unknown id.

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 enumerates the returned analysis fields efficiently. The field list is slightly long but each item tells the agent what to expect, so it 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 an output schema and full read-only annotations, the return values and safety profile are already covered. The gap is parameter guidance: for a tool requiring a message id and an optional firm id, leaving both undocumented makes the definition only adequate, not 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 0% for both parameters, so the description carries the full burden — and it never mentions message_id or firm_id. The phrase 'your firm's' hints that firm scoping is applied, but neither the id format nor the role/default of firm_id is 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?

States a specific verb and resource ('Get one email') plus the payload it returns (full text and AI analysis fields). The singular framing implicitly separates it from the sibling list tool get_email_messages, but that contrast is never stated 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?

Usage is only implied: 'one email ... with its full text and AI analysis' suggests calling it after locating a message id via get_email_messages, but no when-to-use, prerequisites, or alternative is named. An agent must infer the workflow.

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 annotations cannot express: pagination size, sort order, and a nuanced permission model where non-whole-book members see only email linked to their assigned clients plus unlinked email. That access-scoping disclosure materially changes how an agent interprets an empty result 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?

Front-loads purpose and scope before the field list and filters, with no filler sentences. The parenthetical field/classification enumeration is dense but each item informs the agent what it can expect back; a tighter phrasing could have cut a few words without loss.

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 and the description still previews the payload shape adequately, and the permission scoping is covered, which is the main hidden risk here. The gaps are firm_id's role and the exact pagination contract (default page, how to detect the last page).

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 has to carry the load, and it does for most parameters: it supplies the full enum vocabularies for priority and category (which the schema lacks entirely) and explains client_id filtering. It leaves firm_id and the page parameter's mechanics (beyond '25 per page') undocumented, so one of five parameters is unexplained.

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 ('List email messages synced from your firm's connected mailboxes') and immediately scopes it with ordering and page size. The returned-field list and the filter surface make it clearly distinct from get_email_detail (single message) and link_email_to_client (mutation) among the 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?

Gives concrete operating context: newest-first ordering, 25 per page, the filters available, and the visibility rule for members lacking the whole-book role. It does not explicitly route the agent to a sibling (e.g. 'use get_email_detail for the full body'), so the when-not/when-alternative half 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?

Annotations already declare readOnly/idempotent/openWorld=false, so the description correctly spends its words on what the annotations cannot say: the 50-client cap, the least-confirmed-first ordering, how confirmation rate is computed, and the exact urgency thresholds. The one undisclosed trait is what happens past 50 clients (truncation? no continuation path).

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 action and scope, then the sampling rule, then the output shape; no filler sentences. The urgency thresholds are dense but each clause carries information the agent needs to interpret results.

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?

Since an output schema exists, the description needn't restate return values, and the urgency scale explanation is a useful addition. But the meaning of firm_id and the behavior at the 50-client boundary are gaps an agent would hit the moment it needs more than the first page.

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% and the single parameter firm_id is never mentioned in the description. It is optional with an empty-string default, so the agent cannot tell whether omitting it scans the caller's whole book or silently scopes to some default firm — a meaningful ambiguity for a client-facing report.

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 ('Scan the book's active clients ... for incomplete succession planning') with an explicit scope of up to 50 clients ordered least-confirmed first. An agent can tell this is a readiness-gap report, not a client record fetch, 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?

Usage is only implied by the stated scope — nothing says when to reach for this versus get_client_dossier or get_client_reviews_due, nor any precondition such as firm scoping. The agent must infer the call site from the description 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?

The annotations already declare that this is a non-destructive write, idempotent, and closed-world. The description only adds a precondition hint: the message must be visible in your firm's mailboxes and the client must be one you're allowed to change. It says nothing about what happens if the email is already linked to another client, or what a failed link returns. This adds some value over the annotations but not much.

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?

One sentence, and the action is stated up front. The relative clause 'that you may change' is awkward and adds little clarity, but the description is otherwise tight and earns its space.

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?

Because an output schema exists, the description doesn't need to explain return values, and the annotations cover the safety profile. What is missing is the meaning of the identifiers, how duplicates or conflicts are handled, and the purpose of the optional firm_id. That makes it adequate for a simple write tool but not 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 0%, so the description has to carry the full burden. It only indirectly maps 'email message' and 'client' to message_id and client_id, and it never mentions firm_id at all. Format expectations and constraints for the three identifiers are undocumented in both the schema and the description.

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 pair: link an email message to a client. That is enough to separate it from siblings like get_email_messages or get_email_detail, which only read. The trailing phrase 'that you may change' is ambiguous and reads like a fragment, which keeps this from being 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?

The use case is implied: you have an email visible in your firm's mailboxes and you want to associate it with a client. The description never states when to use this instead of another path, or any prerequisites like the email or client needing to exist and be accessible. The intent is inferable but there is no explicit 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context: only active documents, newest first, up to 50 results, and the exact category matching requirement.

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

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

The description is two concise sentences with the core listing behavior, ordering, limit, returned fields, and filter rule front-loaded. It contains no redundant or wasted text.

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

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

An output schema exists, so return values need not be fully documented, and annotations cover the tool's safe read-only nature. The main remaining gap is that household_id is not explicitly described, though the household scoping is clearly implied.

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 compensate. It explains the optional category filter and the exact-match semantics, but household_id is only implied by 'a household's active documents' and is not explicitly defined.

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

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

The description clearly states a specific verb and resource: listing a household's active documents, with ordering and limit. It is easy to distinguish from detail-oriented siblings such as get_document_detail, though it does not explicitly name 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?

The description implies when to use the tool by saying it lists active documents and optionally filters by category. However, it does not explicitly say when to use this versus get_document_detail or how to handle no-category cases, leaving usage guidance only partially addressed.

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 idempotentHint=true, destructiveHint=false, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-schema detail (the allowed status values and YYYY-MM-DD date format), but it never states whether unspecified fields are left unchanged (partial update) or cleared, nor any permission requirements for a mutation 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?

Two sentences with zero filler, and the field list is front-loaded before the status enumeration. The second sentence is a telegraphic fragment, but it is dense with necessary enum detail 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a 7-parameter mutation tool with no schema descriptions, though, the definition leaves firm_id unexplained and the partial-vs-full update contract unstated, which an agent needs before calling it safely.

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 burden; it names five of the seven parameters and supplies the two highest-risk details missing from the schema: the full status enum and the target_date format. Gaps remain: firm_id is never mentioned and goal_id's role/format is left implicit.

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 (update) and resource (client goal) plus the exact fields that can be changed, so the agent knows precisely what operation it performs. It does not explicitly contrast with the sibling create_client_goal or get_client_goals, but the 'update ... goal_id' framing makes the distinction inferable.

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: the presence of a required goal_id signals that an existing goal must already exist and that create_client_goal is for new goals. There is no explicit when-to-use, when-not-to-use, or prerequisite/permission 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 that this is a non-destructive, idempotent mutation, and the description adds the important scope detail that only title and category are changed. It does not add much beyond that, such as confirming other document fields remain untouched, but it is consistent with the annotations.

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

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

The description is a single focused sentence with the key scope up front and no wasted text. The parenthetical adds useful format guidance without bloating the definition.

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

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

The tool has annotations and an output schema, which reduce the description's burden, and it clearly states the mutable fields. However, with 0% schema description coverage across four parameters, it leaves the two required identifier parameters unexplained.

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 parameter meaning. It clarifies title and category, including that category should match list_documents output, but it says nothing about the required household_id and doc_id parameters.

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

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

The description gives a specific verb ('Change') and resource ('household document') and narrows scope to two fields: title and category. An agent can distinguish this from sibling operations like delete_document, upload_document, and list_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?

It implies the tool is for metadata updates and gives a useful category-format reference to list_documents, but it does not explicitly state when to use this versus alternatives or what this tool should not be used for.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: a state-machine constraint on pipeline_stage transitions (no backward moves once ACTIVE/CHURNED) that is not encoded in the schema. It stops short of stating what happens to fields left unspecified or what re-assigning firm_id does.

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 filler. The mutable field list comes first and the state-transition caveat follows, which is the right front-loading for a mutation 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?

An output schema exists, so return values need not be explained, and the destructive/idempotent hints are supplied by annotations. However, for a 7-parameter mutation with zero schema documentation, the description leaves firm_id wholly unexplained and is silent on whether omitted fields are cleared or preserved, which matters given destructiveHint=true.

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 burden of documenting 7 parameters. It names 5 of them (display_name, email, phone, notes, pipeline_stage) but never explains firm_id, which is present in the schema and plausibly re-assigns the client across tenants, nor does it clarify client_id targeting.

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 (update) and resource (client) and enumerates the mutable fields: name, email, phone, notes, pipeline stage. It also distinguishes the operation from the sibling convert_prospect, which is the only path to ACTIVE, so an agent can tell the two apart without opening either 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?

Provides an explicit when-not rule: do not use this to make a client ACTIVE (use convert_prospect), and converted clients cannot be demoted to an earlier stage. It does not cover other alternatives such as update_client_goal, but the critical routing decision is stated.

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

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

The description goes beyond the annotations by disclosing that 'Nothing is stored and no record is created' and that the other arguments are 'accepted but not used' — key operational facts the annotations alone don't convey. However, annotations already carry readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the description's incremental safety contribution is by definition limited (no auth, rate-limit, or error behavior is described).

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 with the critical fact front-loaded ('not available over this connector yet'), and no filler. The last clause about unused arguments is essential context. It is sized appropriately for a stub tool and 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 stub/guidance tool with an output schema present, the description supplies everything needed: the tool is not functional, nothing persists, arguments are ignored, and the real paths are named. No gaps that would cause a mis-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?

With 7 parameters and 0% schema description coverage, the description must compensate — and it does so in the most useful possible way by declaring that every argument besides the implied ones is inert ('accepted but not used'). It doesn't define individual fields like household_id or base64_content, but their semantics are moot given the tool never acts on them.

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 immediately corrects the misleading name: this tool does not upload anything, it 'Returns the ways to add one' (the Antevo Vault or the REST upload flow). That is a specific, unambiguous statement of what the call actually does, and it implicitly steers the agent away from expecting a real document write.

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 plainly that uploading is not possible here and names the two real alternatives (in-app Vault, REST upload), which is exactly the routing information an agent needs. It does not name sibling tools explicitly, so it stops just short of a full when/when-not table.

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