Antevo Mandates

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

No annotations are provided, so the description carries the full burden. It does disclose an authorization requirement (firm OWNER or ADMIN), which is valuable behavior beyond the schema. It omits whether the call is idempotent, what happens if the member is already assigned, and error 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 short, front-loaded fragments with no filler; the core action leads. The role list is a useful compact enumeration rather than prose. Slightly telegraphic, but every element 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?

An output schema exists, so return values need not be described. Still, for a 4-parameter mutation with no annotations, the definition is thin: it never explains firm_id's role, conflict handling, or reversibility, leaving an agent with gaps before a write.

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 4 parameters, so the description must compensate. It documents the valid role values (PRIMARY, ADVISOR, SUPPORT), which the schema does not (no enum, only a default), but leaves client_id, member_id, and especially firm_id (default "") 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?

States a specific verb+resource: 'Assign a team member to an EAM client.' An agent can distinguish it from the read-only sibling get_client_team. However, it does not name an alternative or clarify scope beyond the one sentence, so sibling differentiation is only implicit.

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?

'Needs a firm OWNER or ADMIN' gives a real prerequisite for invoking the tool, which is useful context. But there is no guidance on when to use this versus updating an existing assignment or reading the team via get_client_team, 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?

With no annotations, the description carries the full burden and mostly succeeds: it discloses the specific column mutations (stamps last_reviewed_at, advances next_review_date by next_review_months) and a non-obvious side effect (notes are filed as an OBSERVATION note). It omits auth/permission requirements and idempotency behavior, 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?

The operational content is front-loaded in two tight sentences. The trailing NOTE about the removed review_id parameter is historical context that a caller does not strictly need, though it usefully explains why no id parameter exists.

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

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

For a 4-parameter mutation with no annotations, the description supplies what is mutated, the default roll-forward window, and the note side effect, while an output schema covers return values. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description must compensate: it explains next_review_months (default 12), what notes become (an OBSERVATION note), and effectively client_id as the subject. Only firm_id is left unexplained, so most of the gap is closed.

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 pair ('Record that this client's review is done, and schedule the next one') and names the exact fields affected. It is distinguishable at a glance from the read-side sibling get_client_reviews_due, which queries due reviews rather than completing one.

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 the usage context (after a review has happened) but never states when to use this versus get_client_reviews_due, nor any prerequisite such as first fetching the client. No explicit exclusions or alternatives are named, 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the side effects (household and primary entity creation), but omits whether the operation is irreversible, what permissions are needed, and what the 'confirm' flag does — meaningful gaps 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?

The effect is front-loaded in the first clause and the parameter notes follow in a compact, readable block. The phrase 'as the web's Convert does' adds little for an API agent but is a minor cost.

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 no explanation, and the creation effects are covered. However, for an annotation-free mutation tool, the missing guidance on confirm, permissions, and reversibility leaves the agent without enough to invoke it confidently.

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 and it only partially does: it explains entity_type (enumerated values plus defaulting from client type) and household_name (defaults to client name). The client_id, firm_id, and confirm parameters remain 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?

The description states a specific verb and resource ('Convert a prospect to an active client') and clarifies the concrete effect: it creates the client's household and its primary entity. It reads unambiguously as a lifecycle-conversion operation, distinct from creation-oriented siblings like create_eam_client or create_client_goal.

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 word 'Convert'; there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer that this is the conversion step for an existing prospect, but nothing routes it explicitly against siblings or states 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?

No annotations are supplied, so the description carries the full behavioral burden, and it does not state whether the operation is a mutation, whether it requires permissions, what happens on duplicate goals, or what errors to expect for an invalid client_id. It discloses nothing beyond the enum vocabulary.

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 fragments with the action front-loaded and zero filler; the enum list is the single piece of useful payload. Brevity is appropriate even if the content is thin, so length itself is not the problem.

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 described, but for a 9-parameter mutation tool with no annotations the definition is far too sparse. An agent cannot tell the format expected for target_date, the currency semantics, or how priority interacts with other goals.

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 9 parameters, so the description should compensate, but it only enumerates allowed goal_type values. client_id, goal_name, target_date, target_amount, target_currency, priority, firm_id, and description are all left without meaning, format, or default guidance.

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 ('Create a financial goal'), which is unambiguous and clearly differs from the read sibling get_client_goals. However, it never names or contrasts with update_client_goal, which is the nearest alternative for an agent deciding between creating and modifying, so sibling differentiation is only implicit.

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 guidance on when to create a goal versus updating an existing one or reading goals, nor any prerequisites such as the client_id needing to reference an existing client. Usage is only implied by the verb 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?

No annotations are provided, so the description carries the full behavioral burden for a write operation and does not shoulder it. It never explains the semantics of the 'confirm' flag (default false), whether duplicate detection occurs, what permissions are needed, or what happens to optional fields left blank. Two enum value lists are supplied, but those are parameter-level detail, not behavioral 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?

Two short sentences, purpose front-loaded before the value lists, with no filler or repetition. The terse colon-separated enum format is efficient, though it reads more like schema documentation pasted inline than prose structured for an agent.

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 presence of an output schema means return values need not be described, and the enum lists are a real contribution. But for an eight-parameter mutation tool with zero annotation coverage, the absence of any guidance on the 'confirm' gate, required-versus-optional handling, or firm_id scoping leaves the definition materially incomplete.

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 no parameter carries an enum constraint, so the enumerated values for client_type (INDIVIDUAL, FAMILY, ENTITY) and pipeline_stage (LEAD, PROSPECT, NEGOTIATION, ONBOARDING) are genuinely additive information the agent cannot get elsewhere. However, six other parameters — including the required display_name and the unexplained 'confirm' and 'firm_id' — receive no semantic treatment, so the compensation is only partial.

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 ('Create a new EAM client/prospect'), which is unambiguous and clearly distinct from read siblings like get_eam_clients and mutation siblings like update_eam_client. It stops short of explicitly naming the sibling it is not, so it is clear but not sibling-differentiating.

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 when-to-use guidance and no exclusions. Given siblings such as convert_prospect and update_eam_client exist, the agent gets no help deciding whether to create a new prospect record versus converting an existing one, or when creating a client should be preferred over updating 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the link is public/unauthenticated ('anyone holding it can download'), it expires with a hard cap (720 hours = 30 days), and it is 'Confirm-gated', which explains the confirm flag and warns of a deliberate confirmation step. It stops short of stating permission requirements, whether existing links are replaced/revoked, or idempotency.

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 packs the resource, exposure model, expiry bound, and confirmation gate with no filler. 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?

An output schema exists, so return values need not be described. For a mutation-like tool with no annotations and 0% schema coverage, the description covers the highest-risk facts (public exposure, expiry cap, confirm gate); only permission/revocation behavior and the two identifier params remain 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 0% across 4 parameters, so the description must compensate. It does explain expires_in_hours (default 24, max 720) and ties confirm to the confirm-gate, but household_id and doc_id are left entirely to their names. Partial compensation for a low-coverage 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 ('Create a public link to a document') and adds scope that clarifies the operation: anyone holding it can download. That scope statement is genuinely informative. It does not, however, position itself against any sibling (e.g., upload_document/delete_document), though none of the siblings appear to be share-link 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 only implied by the purpose: you call it when you want to hand a document to an external party. There is no explicit when-to-use, when-not-to-use, or prerequisite (permissions on household_id, whether internal sharing is a different tool). Adequate but with clear gaps.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely important trait: this is a soft delete that sets status to DELETED rather than destroying data. However, it says nothing about the confirm flag (default false), permissions, idempotency, or what happens if the document is already deleted.

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 sentence with no filler, and the key semantic qualifier (soft-delete) is front-loaded. It is efficient, though arguably too sparse for a mutation tool with an unexplained confirmation gate.

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 output schema covers return values and the soft-delete semantics are stated, but for a destructive-intent mutation with no annotations, 0% schema coverage, and an unexplained confirm flag, the description leaves too much for the agent to guess.

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 the description names no parameters at all. The critical 'confirm' boolean with a false default is completely unexplained, so an agent cannot know whether the call actually performs the delete without it.

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 ('delete a document') and qualifies it with 'soft-delete (sets status to DELETED)', which distinguishes it from a hard delete. It does not differentiate itself from siblings like update_document or list_documents, so it lands just 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_document for status changes. The agent must infer the usage context entirely from the verb in the name.

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?

No annotations are present, so the description carries the full burden. It does disclose that the call returns an extraction status, implying an asynchronous job-style operation rather than an immediate result, which is meaningful beyond the schema. It omits permissions, cost/rate limits, and whether repeated triggers re-run OCR or are idempotent.

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, front-loaded sentences with no filler; the action is stated first. Slightly sparse rather than padded, and the second sentence is arguably redundant given an output schema exists.

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

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

Output schema covers return values, so that gap is forgiven, but with zero annotation coverage and 0% parameter documentation the description leaves the agent guessing about the two required IDs, permissions, and whether extraction is async. For a tool whose siblings include upload_document and list_documents, it should say where this fits in the document workflow.

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% — neither doc_id nor household_id has any documented meaning. The description mentions 'a document' generically but never explains what the two required identifiers are, why household_id is needed for a document extraction, or what format they take. It does not 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?

States a specific verb and resource — trigger OCR/data extraction on a document — which an agent can distinguish from read-only siblings like get_document_detail or upload_document. It does not, however, explicitly contrast itself with those siblings or clarify whether extraction is distinct from fetching already-extracted data.

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 when-to-use or when-not-to-use guidance, no prerequisite call (e.g. must the document be uploaded first?), and no named alternative. The word 'Trigger' implies on-demand invocation but nothing tells the agent under what conditions to pick this over update_document or get_document_detail.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool consumes credits and lists the 11 sections, but it does not cover permissions, whether the brief is persisted, idempotency, or execution characteristics.

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 zero waste, packing purpose, scope, and a cost behavior into one tight statement.

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 covered. However, with no annotations and 0% parameter documentation, the description leaves input semantics and usage context largely unexplained for a credit-consuming generation 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 only implies a client via 'for a client' and says nothing about client_id vs firm_id, required status, or format.

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: 'Generate a full meeting brief for a client,' with scope details (11 sections). It is unambiguous, though it does not explicitly differentiate itself from any sibling 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?

There is no guidance on when to use this tool versus alternatives, no preconditions, and no exclusions. 'Consumes credits' is a cost note, not usage direction.

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

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

With no annotations, the description carries the full behavioral burden and discloses almost nothing: 'Get' implies a read, but there is no statement about permissions, whether the dossier is expensive/rate-limited, or what happens with a missing or unauthorized client_id. The output schema covers return values, but the operational profile is undocumented.

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, and the content enumeration is efficient. It is appropriately sized for the amount of information conveyed, though it is arguably under-specified rather than tight.

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 detail is not required. However, with zero annotations, zero schema description coverage, and no usage guidance, the definition leaves the agent guessing about when this aggregate call is preferred over the narrower sibling getters.

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 the description says nothing about either parameter. The required client_id is inferable from 'client dossier', but firm_id (with an empty-string default) is completely unexplained in both schema and description, leaving ambiguity about multi-firm 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 (Get) and resource (client dossier), and enumerates the aggregated contents — profile, entities, AUM, review status, team assignments — which signals it is the composite view rather than a single-facet getter. It does not explicitly contrast itself with siblings like get_client_goals or get_client_team, 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives despite several sibling tools (get_client_goals, get_client_team, get_client_reviews_due) that fetch subsets of the same data. The agent must infer that this is the aggregate call.

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

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

With zero annotations, the description carries the full burden. It implies a read operation and notes it returns progress, but says nothing about permissions, whether firm_id is required for scoping, result limits, or the shape of the goals returned. 'With progress' is the only behavioral detail offered.

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 resource and examples up front and no wasted words. It is close to optimal in size, though the examples slightly crowd out more useful scoping detail.

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 structure need not be explained. However, for a two-parameter read tool with 0% schema coverage and no annotations, the description is thin: it omits firm_id entirely and gives no usage context, leaving gaps the structured fields do not fill.

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 for both parameters. It only implies client_id via 'for a client' and never mentions firm_id, its default-empty behavior, or which parameters scope the lookup. The schema titles ('Firm Id', 'Client Id') are all the agent has to work with.

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: 'Get financial goals for a client', with concrete examples (retirement, education, property) that pin down what a 'goal' is. It contrasts implicitly with the mutation siblings create_client_goal and update_client_goal, but never names them or any read sibling, so differentiation is left to inference.

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, no prerequisites, and no mention of the alternative siblings (create_client_goal, update_client_goal, get_client_dossier). Usage is only implied by the verb 'Get' and the client scoping, leaving the agent to guess when this is preferable to a fuller dossier fetch.

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?

No annotations are provided, so the description carries the full burden. Saying 'Get' implies a read operation and the omission rule discloses a scope-escalation behavior (all clients), which is genuinely useful. However, it says nothing about permissions, what 'due' means (date window, status filter), or result size/pagination.

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 sentence with zero filler; the scope rule is front-loaded and the description is appropriately sized for a two-parameter read 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. Still, with no annotations and zero schema coverage, the definition leaves firm_id's role and the meaning of 'due' unstated, which an agent would need in order 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 must compensate, and it only explains client_id (optional, omission widens scope). firm_id, despite having a default, is left completely undefined, so half the parameters remain opaque in both schema and 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?

States a specific verb and resource ('Get compliance reviews due') plus the scope, which is clear enough to distinguish from siblings like get_client_goals or get_client_team that return different resources. It does not name any sibling 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 description gives one branching condition ('or all clients if client_id omitted'), which tells the agent how the tool behaves in two modes, but it does not say when to prefer this tool over alternatives or what prerequisites (e.g., a firm context) are needed. Usage is implied rather than guided.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The word 'assigned' hints that only assigned (not all) members are returned, but nothing is said about permissions, whether results are paginated, or what an empty team returns.

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 or repetition. It is efficiently sized for a simple two-parameter read, though it is arguably under-specified rather than merely concise.

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 described. However, with no annotations, 0% parameter coverage, and no usage context, the definition leaves an agent missing key information about parameter semantics and scoping 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 0%, so the description must compensate for the two undocumented parameters and does not. It never explains what client_id identifies or how the optional firm_id scopes the lookup, leaving the agent to infer the firm/client relationship.

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'), resource ('assigned team members'), and scope ('for an EAM client'), so the agent knows exactly what is returned. It does not explicitly distinguish itself from the sibling assign_team_member (the write counterpart), but the read framing 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?

There is no guidance on when to use this tool versus alternatives such as get_client_dossier or assign_team_member. No prerequisites, no exclusions, and no context on when team membership data is the right thing to fetch.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the response exposes ACLs and share links (sensitive surfaces an agent wouldn't otherwise anticipate), and 'Get' implies read-only, but it says nothing about permission requirements for reading ACLs or whether access failures are returned.

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

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

A single well-formed sentence with the resource and returned fields front-loaded and no filler. It is tight, though extremely brief for a tool with two undocumented required parameters.

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 read semantics are implied by 'Get'. However, with 0% schema coverage on two required params and no annotations, the description leaves the most error-prone part of invocation (which identifiers to supply) unaddressed.

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 doc_id nor household_id is described. The description only implies that a document identifier is needed ('for a specific document') and never explains household_id or the relationship between the two required identifiers.

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 ('Get') and resource ('document'), and enumerates the payload contents (metadata, ACLs, share links), so an agent knows exactly what it retrieves. It gives no hint of how it differs from siblings like list_documents, extract_document_data, or update_document, 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?

There is no statement of when to use this instead of list_documents or extract_document_data, and no prerequisites or exclusions. The phrase 'for a specific document' hints at single-item scope but leaves the choice between siblings 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?

No annotations exist, so the description carries the full behavioral burden. 'List' implies a read operation, but it says nothing about pagination, result limits, permissions, or whether the list is complete—significant gaps for a list tool with no structured safety hints.

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 primary purpose and followed by filtering options. No wasted words.

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

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

An output schema exists, so return values needn't be described, and the read-only nature is low risk. But the missing firm_id explanation and absence of pagination/limit behavior leave gaps 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 0%, so the description must compensate, and it partially does by naming status values (ACTIVE/ARCHIVED), pipeline_stage, and search. However, firm_id (with a default) is never explained, leaving one of four params undocumented in both schema and 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?

States a specific verb (List) and resource (EAM clients) scoped to a firm, which clearly separates it from siblings like create_eam_client or update_eam_client. It doesn't explicitly contrast with detail-oriented siblings such as get_client_dossier, keeping it just below top marks.

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 filtering options hint at when this tool applies (browsing/filtering clients), but it never states when to prefer it over get_client_dossier or convert_prospect, nor mentions preconditions. Usage is implied 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.

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

No annotations are provided, so the description carries the full burden; it discloses the analytical payload (sentiment, summary, topics, compliance flags, suggested action), which is genuinely useful. It does not state read-only semantics explicitly, cost/latency implications of running AI analysis on every call, or what happens if the message_id is unknown or belongs to another firm.

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 with the resource and the value proposition front-loaded and no filler. It is appropriately sized for a two-parameter read tool, though the enumerated field list is the only content it offers.

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 need not be described, and the description's field list is a helpful preview. However, for a tool with an undocumented firm_id parameter, no annotations, and AI-derived fields that may have accuracy or compliance implications, key operational context 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 0% for two parameters, and the description supplies nothing about either. message_id's role is guessable from the name, but firm_id has a default of empty string and no explanation of whether it is a tenant scope, an optional override, or required for access control — a real ambiguity the description should resolve.

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 (full email) and an enumeration of the returned analysis fields. It implicitly contrasts with the sibling list tool get_email_messages via 'full email,' but never names it, so 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?

Usage is only implied: the word 'full' suggests fetching a single detailed record rather than a list, but the description never says 'use this after get_email_messages' or states any precondition. An agent must infer the retrieval-vs-listing split from sibling names 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?

No annotations are provided, so the description carries the full behavioral burden, and it only adds the vague phrase 'with AI analysis'. It does not disclose ordering, pagination semantics for the page parameter, whether filters are combined with AND, or any auth/rate-limit context.

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 that are front-loaded with the core action and follow with filters; every clause carries information. The trailing filter list is slightly list-like rather than prose, 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?

An output schema exists, so return values need not be explained, and the filter parameters are described. What is missing for a five-parameter listing tool with no annotations is pagination behavior and guidance on selecting this tool over get_email_detail.

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, and it does document three of five parameters including enum values (CRITICAL/HIGH/MEDIUM/LOW and INQUIRY/INSTRUCTION/UPDATE) that appear nowhere in the schema. However, page and firm_id remain completely undocumented, leaving the parameter picture incomplete.

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 (email messages) plus scope (for an EAM firm with AI analysis), so an agent immediately knows this is a bulk retrieval, not a single-record fetch. It does not explicitly name get_email_detail as the sibling it contrasts with, 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?

There is no when-to-use or when-not-to-use guidance and no mention of the sibling get_email_detail, which is the obvious alternative for a single message. The only hint is the word 'List' in the tool name, which is not stated in the description 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?

With no annotations, the description carries the full burden. It discloses the firm-wide scope and that results concern incomplete succession planning, but says nothing about permissions, how 'urgency' is ranked, whether results are ordered, or what the scan touches. For an unannotated tool this is thin.

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 scope and the discriminating condition arrive immediately. It is efficient, though arguably too terse to cover the gaps elsewhere.

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. However, for a scan tool with zero annotations and a 0%-documented parameter, the description leaves real gaps: firm_id behavior and what makes a client 'urgent' remain undefined.

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 the single parameter (firm_id, default '') is undocumented in both schema and description. The phrase 'firm-wide' hints the tool is firm-scoped but never explains what firm_id does or what an empty value means, so the agent must 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?

The description names a specific action ('urgency scan'), a resource ('succession planning'), and a scope ('firm-wide'), plus the qualifying condition ('incomplete succession planning (EAM)'). An agent can tell it apart from generic siblings like get_eam_clients or get_client_dossier, though it doesn't explicitly name the alternative it differs from.

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 outcome statement ('identifies clients with incomplete succession planning') implies the use case — assessing succession risk across a firm — but the description never states when to reach for this versus get_eam_clients or get_client_dossier, nor any prerequisites or exclusions.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses almost nothing. It does not say whether the link is idempotent, what happens if the message is already linked to another client, whether it requires write permissions, or whether the operation is reversible.

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 short sentence with zero padding and the core operation front-loaded, so it is not verbose. However, its brevity is under-specification rather than efficiency, since the tool is a mutation with unaddressed behavioral and parameter questions.

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 described, but for a mutation with no annotations and 0% schema coverage the description is far too thin. An agent cannot tell from this text what preconditions hold, what side effects occur, or how to populate firm_id.

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 three parameters. The phrase 'email message' and 'EAM client record' loosely maps onto message_id and client_id, but the third parameter, firm_id, is never explained, nor is the expected ID format or whether firm_id defaults to the caller's firm when 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?

The description states a specific verb (link) and both resources (an email message and an EAM client record), which is far more informative than the bare tool name. It stops short of a 5 because it does not distinguish this tool from siblings like assign_team_member or create_eam_client, which also attach entities to records.

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 guidance on when to use this tool, what prerequisite state must exist (e.g., the email and client must already be known to EAM), or what the alternative is if the email is not yet imported. The sentence merely restates the operation, leaving all routing decisions 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?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about pagination, result limits, ordering, or permission requirements for reading a household's documents. It implies a read operation but does not confirm that it is non-mutating or describe what a result set 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?

Two short sentences, zero filler, with the primary action stated first and the optional filter second. Nothing is redundant with the title or schema field names.

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 tool is a simple two-parameter list. However, the description omits what household_id means (and why it defaults to empty rather than being required) and says nothing about result size or pagination, leaving gaps for a 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 0%, so the description must compensate. It adds real meaning for category by giving example values (STATEMENT, TAX, LEGAL) that the schema lacks, but household_id is never mentioned even though its empty default is ambiguous. Partial compensation justifies the middle score.

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

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

States a specific verb (List) and resource (documents) with scope (for a household), which is enough to distinguish it from get_document_detail, delete_document, update_document, upload_document and extract_document_data. It does not explicitly name or contrast with any sibling, 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 only usage signal is 'Optionally filter by category', which describes a parameter, not when to call this tool versus alternates. There is no guidance on when to use list_documents instead of get_document_detail or extract_document_data, and no exclusions or prerequisites are given.

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?

No annotations are provided, so the description carries the full burden. 'Update' signals mutation, but there is no disclosure of permissions required, whether it is a partial or full update, what happens to omitted fields, or side effects like status-change notifications. Enumerating the status values is genuinely useful but is the only behavioral detail offered.

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, front-loaded with the action and then the status vocabulary. Every sentence earns its place; the terseness reflects under-specification elsewhere, not verbosity.

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

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

An output schema exists, so return values need not be described. However, for a 7-parameter mutation tool with no annotations and no parameter documentation, the description is far too thin to let an agent invoke it confidently.

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 7 parameters, so the description must compensate. It only defines the allowable values for status (which the schema does not encode as an enum). goal_id, firm_id, notes, target_date, target_amount, and current_amount are entirely unexplained in both places.

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: updating a client goal's progress. It is clearly distinct from create_client_goal and get_client_goals by verb alone. It stops short of explicitly naming sibling alternatives, but the purpose 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?

No guidance on when to use this tool versus create_client_goal or get_client_goals, and no prerequisites or context signals. The agent must infer that this is the mutation path for goals that already exist.

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

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

With no annotations, the description carries the full behavioral burden. It says 'update' but never discloses whether this is a partial or full replacement, what happens to fields omitted from the call, whether permissions or ownership are required, or that the operation is a mutation with any side effects.

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 zero filler, and the field list is packed economically after the em dash. It is arguably too terse for a five-parameter mutation tool, 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?

An output schema exists so return values need not be described, but for a mutation tool with no annotations and no schema descriptions the definition is thin. Partial-update semantics, behavior on omitted fields, and permission requirements are all unaddressed.

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, and it does partially: it names the three updatable fields and adds the genuinely useful format note that tags are comma-separated. However, the two required parameters (household_id, doc_id) are unexplained, and it does not clarify that the listed fields are optional while the identifiers are mandatory.

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 (document) and narrows the scope to metadata fields — description, category, tags. This implicitly separates it from content-oriented siblings like upload_document or extract_document_data, but it never names an alternative or explicitly rules out document content changes.

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 when-to-use, when-not-to-use, or alternative-tool guidance is given. The 'metadata' qualifier hints at scope but does not tell an agent whether to reach for this versus upload_document, delete_document, or create_share_link.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose one non-obvious constraint: pipeline_stage cannot be set to ACTIVE via this tool. That is genuinely useful and not derivable from the schema. But it omits the biggest behavioral question for a seven-optional-field update — whether omitted fields are left unchanged or cleared — as well as permission requirements and error 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?

Two short sentences with zero waste; the core action is front-loaded and the routing constraint follows immediately. Nothing redundant or 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 explained, and the description correctly flags the pipeline_stage trap. But for a mutation tool with no annotations and 0% parameter coverage, the definition is still thin — partial-update semantics, required permissions, and handling of unknown client_id are all 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 0% across 7 parameters, so the description must compensate, and it only adds meaning for one field (pipeline_stage's ACTIVE restriction). The other six fields (email, notes, phone, firm_id, display_name, client_id) get no semantics, format hints, or mutability notes from either source.

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 ("Update an EAM client record"), which clearly distinguishes it from read-side siblings like get_eam_clients and from create_eam_client. It also names convert_prospect as the tool for a specific transition, so an agent can partly route between them, though it never contrasts itself with create_eam_client or update_client_goal.

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 one explicit when-not plus the alternative: pipeline_stage cannot be set to ACTIVE here, use convert_prospect. That is concrete routing guidance. However, it offers no general context for when to update an existing client versus creating one, and no prerequisites (e.g. required permissions or valid client_id sourcing).

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the important write behavior: what gets stored when base64_content is present and what is returned otherwise. However, it never explains the 'confirm' boolean parameter, which strongly suggests a confirmation or dry-run semantic that an agent needs to understand before writing, and it says nothing about permissions or side effects.

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?

Dense and front-loaded: the core action comes first, followed by the enumerated values and the conditional storage behavior. The enum lists consume space but are necessary since the schema lacks them.

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 mutation tool with zero annotations and 0% schema coverage, key operational details are missing: what household_id scopes, what confirm does, and whether a call without base64 leaves a dangling placeholder record. Only the output-schema-adjacent detail (doc_id) is covered.

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

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

Schema description coverage is 0%, so the description must compensate. It does supply the allowed values for domain and category (which the schema does not enumerate) and explains base64_content's dual behavior, but household_id, file_name, description, and confirm remain completely undocumented across four of seven parameters.

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

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

The description states a specific action (initialize a document record) plus the conditional blob-storage behavior, which lets an agent distinguish it from get_document_detail, update_document, and list_documents. It never names a sibling explicitly, and the verb 'Initialize' is slightly at odds with the tool name upload_document, but the overall intent 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?

It implies two invocation modes (inline base64 vs. two-step doc_id upload), which is useful usage context, but it gives no guidance on when this should be used instead of update_document or extract_document_data, and no prerequisites or exclusions are stated.

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