Lovie Company Formation

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read-only' line merely restates that safety profile. It adds some value by disclosing the flat-list-with-parent-links shape and the requirement to build the tree client-side, but it does not cover other behaviors like whether inactive accounts appear by default.

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

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

Two sentences with the key format constraint ('flat list with parent links; build the tree client-side') front-loaded. The only waste is the 'Read-only' sentence, which duplicates the annotations, and the name-echoing opener 'GetChartOfAccounts returns'.

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 return structure is already covered, and the description adds the client-side tree-building nuance. However, the boolean parameter includeInactive semantics are unexplained, so an agent cannot know what the default output contains or how to filter it without out-of-band knowledge.

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

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

Schema coverage is 50% and the description adds no parameter information at all. The schema's companyId description ('UUID value wrapper') only describes the wrapper structure, not its source or semantics, and includeInactive is entirely undocumented. The description fails to compensate for the coverage gap.

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

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

The description states a specific verb and resource: it returns the company's chart of accounts. It also adds a distinguishing format detail (flat list with parent links, tree built client-side), which separates it from report siblings like accounting_get_balance_sheet or accounting_get_general_ledger, though it does not name them 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 implied: call this when you need the chart of accounts in a flat, client-constructed hierarchy. However, there is no explicit when-not-to-use guidance or comparison against sibling account/ledger tools, so the agent must infer when this is the right choice.

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 and destructiveHint=false. The description adds valuable context: the data is static per release and safe to cache, which goes beyond the annotations. It also clarifies the tool returns a pairing of account types to detail types, giving a behavioral understanding of the data shape. No contradiction with annotations.

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

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

Two sentences: the first explains the function and use case, the second adds cacheability and read-only confirmation. No redundant phrasing, and the most important info is front-loaded. Every sentence earns its place.

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

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

The tool has an output schema, so return values are defined elsewhere. The description covers the purpose, the static nature, and the specific use case. One parameter is documented in the schema. It's complete for a read-only catalog tool; no missing prerequisites or error conditions are critical to mention.

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

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

The single parameter companyId is fully described in the input schema as a 'UUID value wrapper' (100% schema coverage). The description adds no additional semantics about the parameter. Baseline of 3 is appropriate since the schema carries the burden.

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

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

The description states a specific verb (returns) and resource (every account type with detail types and classification). It clearly distinguishes this from the chart of accounts tool by focusing on the account type catalog needed for the New account panel's dependent selects. The purpose is unmistakable.

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

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

The description provides clear context: it's the data needed for the New account panel, and it's static per release with safe caching. However, it doesn't explicitly name alternatives or exclusion conditions, though the use case is well defined. This is better than implicit usage but lacks explicit 'when not to use' 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 and destructiveHint=false, so the description does not need to restate safety. It adds some behavioral context by indicating pagination and company scope, but it does not disclose filter behavior, ordering, or iteration semantics beyond what the schema implies.

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 very short and action-oriented, with no filler. The phrase 'GetListSchedules' is redundant with the tool name and reads like code rather than natural prose, but the overall structure is scannable and front-loaded.

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

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

The output schema covers return shape, and annotations cover safety, so the description does not need to explain those. However, it omits guidance on filtering by status, how pagination tokens work, and when this list should be used instead of fetching a single schedule. It is adequate but has clear gaps.

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

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

Schema description coverage is only 25%, with only companyId described as a 'UUID value wrapper.' The description adds minimal parameter meaning beyond the word 'pages through,' which hints at pageSize/pageToken but does not explain filter.statuses, required parameters, or pagination conventions. The schema helps via enums and bounds, but the description does not compensate for the low 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 states a clear verb ('pages through') and resource ('a company's schedules'), making the tool's function obvious. It does not explicitly differentiate from accounting_get_schedule or other schedule-related siblings, but the plural list semantics are reasonably clear from the name and description.

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 no explicit guidance on when to use this tool versus accounting_get_schedule, accounting_create_schedule, or accounting_cancel_schedule. The only hint is the pagination framing, which implies a list operation, but no alternatives or conditions are 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 already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds useful behavioral context beyond annotations: results are ordered 'newest period first' and include unmatched line counts per statement. It does not cover pagination or limits, but the output schema and low complexity reduce the need.

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 efficient sentence, front-loads the verb and resource, and packs ordering and unmatched-count behavior without redundancy. Every clause earns its place.

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

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

For a simple read-only list operation with an output schema and safety annotations, the description is largely complete. It conveys what is listed, the ordering, and the key metric, though it could strengthen context by mentioning the optional accountId filter or routing to the singular get_statement 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 100%, so the baseline is 3 even without extra parameter explanation. The description adds no parameter-specific meaning, and the schema only describes each parameter as 'UUID value wrapper,' leaving the role of optional accountId 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?

The description clearly states the action ('List'), the resource ('bank statements imported for reconciliation'), and adds meaningful specifics: newest period first and unmatched line counts. This distinguishes it from nearby siblings like accounting_get_statement and accounting_get_list_journal_entries.

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 its use case: when you need an overview of imported bank statements and their reconciliation progress. However, it does not explicitly name alternatives or state when not to use it, such as when a single statement's full detail is needed via accounting_get_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 provide readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' is redundant. It adds useful context by specifying that the result includes postings, which is not required by the schema. No contradictions with annotations; the additional behavioral detail is minimal but relevant.

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 one concise sentence plus a redundant 'Read-only.' Every phrase is informative: it names the resource, scope, and included data. There is no waste, and the key information is front-loaded.

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

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

For a read-only operation with two self-explanatory parameters and an existing output schema, the description covers the essential behavior: what is returned (one schedule with postings) and its safety (read-only, also in annotations). Details like error handling or prerequisites are not necessary for correct invocation given the annotations and 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 100%: both parameters (companyId and scheduleId) are described as UUID value wrappers, which adequately defines their structure. The description adds no extra semantics about parameter meaning or usage. With full schema coverage, baseline 3 is appropriate.

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

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

The description is clear and unambiguous: 'GetSchedule returns one schedule with its postings.' It specifies the verb (Get), resource (schedule), and scope (one schedule), which distinguishes it from list-type tools like accounting_get_list_schedules. The phrase 'with its postings' adds useful detail not obvious from the name.

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 states what the tool does but does not provide explicit when-to-use guidance or name alternatives. The distinction from accounting_get_list_schedules is implied by the tool name and the singular 'one schedule,' but the agent must infer when to choose this over siblings. No exclusions or context 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the operational safety profile is covered. The description's 'Read-only' merely repeats the annotation, but 'with its lines and their matches' adds useful context about what the response contains. No additional behavioral details such as error conditions, company scoping, or output shape are disclosed.

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 extremely compact: two short sentences, front-loaded with the core meaning and ending with the read-only qualifier. Every word earns its place, and there is no redundant filler or restating of 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 simple read-only retrieval tool with two required UUID parameters, an output schema, and robust annotations, the description is nearly sufficient. It states the single-statement scope and what is included (lines and matches). The only missing contextual element is explicit routing to list-oriented siblings, but that is more of a usage-guidance refinement than a completeness gap.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description itself adds no parameter information. Both parameters are documented only as 'UUID value wrapper,' which is formal but not semantically rich; parameter names statementId and companyId carry the actual meaning. The description neither compensates for nor worsens this situation.

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 identifies the resource as a single statement and specifies that it includes lines and their matches, which distinguishes it from listing tools like accounting_get_list_statements. The verb is only implicit through the title 'Get Statement,' but the scope and content are unambiguous. It could be stronger by explicitly contrasting with sibling getters, so it does not quite reach 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 'One' implies this tool is for retrieving a specific statement rather than listing statements, giving minimal usage context. However, it does not explicitly state when to prefer this over accounting_get_list_statements or other statement-related tools. Usage guidance is present only by implication, not by explicit exclusions or alternatives.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, so the description adds the 'straight-line per-period split' computation detail and 'without persisting anything', which are useful beyond the annotations. No contradiction exists; the description reinforces the read-only nature.

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

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

Two sentences, no filler, and the key information (non-persisting, read-only) is front-loaded. Every word earns its place, making it an exemplary concise description.

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

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

Although the tool has an output schema (so return values are covered) and annotations handle safety, the description leaves startDate unexplained, which is a core input for a schedule preview. It also does not clarify whether startDate influences the split (e.g., determines the first period). This gap makes it incomplete for a 3-parameter 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 explain all parameters. It mentions 'given amount and period count' but completely omits startDate, leaving its purpose unclear. It also does not clarify that totalAmount is a string with decimal format, which is non-obvious. The description adds only partial meaning, failing to compensate for the schema's lack of detail.

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 (computes) and resource (straight-line per-period split) and explicitly notes it does not persist anything, distinguishing it from accounting_create_schedule and accounting_get_schedule. The read-only nature is also stated, making the tool's purpose unmistakable.

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

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

The description implies when to use it ('without persisting anything' suggests preview before commit) but does not explicitly name alternatives or exclusion criteria. It conveys the context effectively, though it could be more direct about when not to use it (e.g., when you need to save).

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 only openWorldHint=false and destructiveHint=false in annotations, the description adds meaningful behavior: it explicitly says the aggregation happens at read time and creates no new storage. That is useful context beyond the annotations, though it does not cover permission or freshness details.

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

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

The description is two short sentences, with all information front-loaded. It wastes no words and packs the source, operation, output dimensions, and storage behavior into a compact form.

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

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

For a tool with an output schema and three self-naming parameters, the description covers the key details: data source, grouping, metrics, and side-effect-free behavior. It is slightly incomplete only because it does not address parameter roles or when to prefer this tool over its close siblings.

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

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

Schema description coverage is 0%, and the description does not explain how companyId, periodStart, or periodEnd affect the aggregation. The parameter names and date patterns are self-explanatory, but the description adds no semantic detail such as inclusivity, defaults, or how the period maps to the monthly grouping.

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 operation (unions four ad platforms' daily tables at read time) and a concrete result (per-provider/month/currency spend/impressions/clicks/conversions plus CPA), which clearly identifies what the tool does. It does not explicitly name a sibling alternative, but the four-platform aggregation is enough to set it apart from the per-platform campaign-window tools.

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

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

No guidance is given on when to choose this tool over ads_insight_summarize_campaign_window or the per-platform metric tools. The read-time/no-storage note implies a safe aggregation use case, but it does not state prerequisites, exclusions, or alternatives.

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

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

Annotations only provide openWorldHint=false and destructiveHint=false. The description adds non-obvious behavioral context: results are cached per company + account + window + charge, and repeated panel opens do not re-run the agent. This is genuinely useful beyond the annotations and does not contradict them.

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

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

Two concise sentences with no filler. The core purpose and scoping constraints are front-loaded, and the caching behavior is a relevant secondary detail. Every sentence earns its place.

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

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

The output schema and annotations cover return shape and safety profile, but the description omits usage routing versus sibling tools and leaves parameter semantics almost entirely to parameter names. With six optional parameters and zero schema descriptions, an agent cannot confidently construct a correct invocation.

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

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

Schema description coverage is 0% for six parameters. The description indirectly maps 'company + account + window + charge' to likely parameters, but it does not explain provider semantics, date formats, optionality, chargeAmount syntax, or what happens when parameters are omitted. It only partially compensates for the schema 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?

Description uses a specific verb ('summarises') and identifies the resource: one charge against the campaigns in its billing window. This is more specific than the title and implies a distinct role from the per-provider get_campaign_window siblings, though it does not explicitly name them.

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

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

No guidance on when to use this tool versus the closely related per-provider siblings (google_ads_metrics_get_google_ads_campaign_window, meta_ads_metrics_get_meta_ads_campaign_window, etc.). The caching note hints at a UI/panel context, but it never states selection conditions, exclusions, or alternatives.

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

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

Annotations only declare openWorldHint=false and destructiveHint=false, so the description carries the behavioral disclosure burden and it delivers: it discloses the push-notification side effect on the user's device, the required human approval step, session expiry in minutes, and single-use consumption. This is all context the annotations do not provide, and nothing in the description contradicts 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?

A single dense paragraph of roughly 60 words with the core purpose front-loaded before the workflow, lifecycle constraints, and sibling routing. Every clause earns its place — purpose, gated-tool examples, step sequence, expiry, and single-use — with no filler or restatement of the 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 need no explanation, and the description covers the what, when, and full follow-up workflow plus expiry and single-use semantics. Minor gaps remain: no polling cadence, no failure-handling guidance for user denial or mid-flow expiry, and 'minutes' is imprecise; but nothing essential to invoking the tool correctly is missing.

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

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

With schema description coverage at only 17% (one of six parameters documented, and that one only as 'UUID value wrapper'), the description must compensate, and it does for two of six: 'create the session with the exact action_type and payload the tool documents' tells agents that actionType and actionPayload are not free-form but must mirror the gated tool's documented values. originLocation, originPlatform, actionDescription, and originTrustedDeviceId remain unexplained, with only a loose hint that the intended device is 'trusted.'

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 and resource — 'Opens a sensitive-action approval on the user's own trusted device' — and explains the delivery mechanism (a push notification asking them to approve on their phone). It also differentiates itself from its only sibling, approval_session_get_approval_session_status, which the description explicitly names as the subsequent polling step.

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

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

The description explicitly states when to use the tool ('Use before tools that demand an approval') and names concrete gated tools: the domain auth-code reveal, the trademark firm handoff, and the ITIN submit. It then gives the full orchestration sequence — create the session, tell the user to check their phone, poll get-approval-session-status until APPROVED, pass the session id to the gated tool — leaving no ambiguity about 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavior the annotations cannot: the ~5 minute expiry window after the session was opened and the explicit anti-polling instruction ('not in a loop'), which is real operational context. It stops short of describing the response shape, though an output schema exists.

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

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

Front-loaded with the core action and the status values, then layers usage constraints and lifecycle facts in two tight sentences. Every clause earns its place; no filler or redundant restatement of the 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?

For a polled status tool with annotations covering safety and an output schema covering return values, the description supplies everything else an agent needs: the possible statuses, the caller sequence, the polling cadence, and the expiry window. Nothing material 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 100% and there is only one parameter, so the schema carries the type/format burden. The description goes beyond it by specifying the provenance of the value ('the approval_session_id from request_transfer_approval'), which tells the agent where to obtain the id rather than just its shape.

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

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

States a specific verb and resource ('Read the status of a trusted-device approval session') and enumerates the exact status values (PENDING, APPROVED, REJECTED, EXPIRED), which pins the resource down precisely. It is clearly distinguishable from the sibling request_transfer_approval and commit_transfer that it references.

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

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

Explicitly names the trigger (once the user says they have answered on their phone), the id source (from request_transfer_approval), the downstream action gated on the result (call commit_transfer only when it returns APPROVED), and the polling policy ('once per user prompt, not in a loop'). This is textbook when/when-not/alternative guidance with nothing left to inference.

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

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

Beyond the annotations, the description discloses non-obvious behavior: it runs a 'four-check pipeline' and a 'per-agent autonomy fence,' and redirects out-of-envelope payments to human approval. This gives an agent useful insight into side effects and gating, though the pipeline steps and envelope criteria remain vague.

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

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

Two tightly-written sentences with no filler. The primary action is front-loaded, and the second sentence adds meaningful behavioral context without 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?

For a 4-parameter tool with no schema descriptions and substantial behavioral implications, the description is too thin. It omits parameter semantics, pipeline details, envelope determination, and what happens after human approval, leaving an agent to guess at critical invocation details.

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, but it only mentions a 'signed payment mandate' at a high level. It does not explain the role of jcsHash, how serviceLevel affects execution, what format mandateBodyJson should take, or what signatureB64url signs.

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 ('Submit'), a specific resource ('a signed payment mandate'), and a clear purpose ('autonomous execution'). This distinguishes it from drafting/confirming payment tools, though it does not explicitly name sibling 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 phrase 'for autonomous execution' implies the intended use case, and the autonomy fence comment clarifies when human approval is triggered. However, it does not explicitly state when to use this tool versus draft_payment, confirm_payment, or other payment-related alternatives, leaving the routing partially 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 cover safety (idempotent, non-destructive, closed-world), and the description adds meaningful state behavior beyond that: it records human verification and gates the section's open/closed state and final submission. It doesn't mention required permissions, but the blocking consequence is genuinely useful 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, front-loaded with the action and followed by the consequence. No filler, though it is slightly terser than the domain's complexity warrants.

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 core blocking rationale is present. However, for a nested-schema tool with an undocumented fieldPath, the description leaves the agent guessing about what a 'section' is and how a value is identified.

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

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

Schema coverage is only 50%, and the description does not compensate. It speaks of 'a read value' but never connects that to fieldPath, explain its dotted-path pattern, or clarify that applicationId is a UUID wrapper. fieldPath's meaning must be inferred entirely from the regex constraint.

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: recording that a human checked a read value, tied to the extraction/application workflow. It's clear what the tool does, though it never names a sibling (e.g. banking_extract_document_fields or banking_submit_banking_application) to distinguish itself positionally.

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

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

Usage is implied by the consequence: without it a low-confidence extraction holds its section open and blocks submission. This tells the agent the trigger condition, but offers no explicit when-not guidance and names no alternative path.

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 only openWorldHint: false and destructiveHint: false in annotations, the description carries the behavioral burden and delivers: it discloses the write is intention-only, that no funds are transferred by any part of Lovie today, and instructs the agent never to claim the deposit was sent. This goes well beyond what the annotations convey about side effects and user-facing truthfulness. No contradiction with annotations exists — a non-destructive, closed-world intent recording aligns with destructiveHint: false and openWorldHint: false.

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

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

Three sentences, with the core purpose front-loaded in the first sentence. Each subsequent sentence earns its place by clarifying the non-transfer behavior and a critical communication constraint; there is no filler or redundancy.

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

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

The description fully covers what the tool does, what it does not do, and the key user-communication rule, and an output schema exists so return values need not be described. The main residual gap is the semantics and optionality of amount and currencyCode, which are not addressed in the description.

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 only 33%, and the sole parameter description is the thin 'UUID value wrapper' for applicationId. The tool description does not compensate: it never states that amount represents the deposit value, that it is actually optional despite only applicationId being required, or that currencyCode is an optional ISO code. An agent must infer the meaning of amount and currencyCode from pattern constraints in the schema.

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

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

The description names a specific verb, 'Records,' and a specific resource, the opening deposit a founder chose for their banking application. It immediately clarifies scope by stating it 'stores an intention only' and that no money moves, which distinguishes it from the many money-movement siblings (commit_transfer, draft_payment, autonomous_pay).

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 sets clear context, indicating this is the step that records the founder's deposit choice as an intention, and explicitly states the tool does not move money. It lacks explicit naming of alternatives such as banking_get_initial_transfer_preview or commit_transfer, so guidance is contextual rather than directive. The 'Never tell the user their deposit has been sent' line adds a useful behavioral boundary.

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 openWorldHint=false and destructiveHint=false, so the description carries most of the behavioral burden. It usefully discloses that each filled value is marked with its source and read confidence, and that it deliberately skips industry classification. It does not state auth requirements or whether the write is reversible, so it isn't fully complete.

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 core action and document scope, followed by a precise scope boundary. Every clause earns its place with no filler.

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

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

With an output schema present, the description need not explain return values, and it adequately covers the action, input document types, and one important exclusion. The remaining gap is the absence of explicit alternatives or prerequisites, which is minor given the rich structured fields.

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

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

Schema description coverage is 100% and both parameters are documented as UUID value wrappers, so the schema does the heavy lifting. The description adds no field-level detail (e.g., which application/document must exist or format expectations) beyond what the schema already provides.

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: reads an uploaded document (Certificate of Incorporation or IRS EIN letter) on a banking application and fills in stated values. It also bounds scope by stating it never sets industry classification. It does not name or contrast sibling hydration tools like banking_hydrate_from_formation, so it is clear but not fully differentiated from 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?

The two document types indicate the intended input context, and 'It never sets the industry classification' implicitly routes that concern to a suggest/confirm sibling. However, there is no explicit when-to-use vs when-not guidance or a named alternative tool, so usage must be inferred.

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

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

Beyond the readOnly/non-destructive annotations, the description discloses meaningful behavioral traits: it carries only the last four digits of the EIN and each owner's tax identifier, the undivided values live in the secret store, and full-identifier retrieval is a separate deliberate RPC that is not exposed as a tool. This is exactly the kind of security/return-shape context annotations cannot convey.

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

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

The description is front-loaded with what the tool returns, followed by the usage framing and the security caveat. Every sentence carries information, though the closing security rationale is slightly discursive for a tool description.

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

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

With an output schema present, return values need no prose explanation, and annotations cover the safety profile. The description complements these with payload scope, outstanding-sections context, and the identifier-truncation behavior, leaving nothing an agent needs to call it correctly unstated.

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

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

Schema description coverage is 100% and both parameters (companyId, applicationId) are documented as UUID wrappers in the schema. The description adds no additional meaning about their format or requiredness, so this sits at the baseline where the schema does the work.

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

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

States a specific verb (returns/gets) and resource (the whole banking application), then enumerates the exact payload: business facts, beneficial owners, uploaded documents, value sources, and outstanding sections. This level of specificity tells an agent precisely what it will receive and implicitly separates it from write siblings like banking_update_banking_application and banking_submit_banking_application.

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 is the one read for answering 'where is my application, and what is left?'" gives a clear intent-based condition for selecting this tool. It offers no explicit exclusions or named alternatives, but the usage context is unambiguous and sufficient for selection.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds concrete behavioral assurance: 'it moves no money and records nothing.' This goes beyond the structured hints by spelling out the actual side-effect-free behavior, which is valuable for a banking-related 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 short sentences deliver the core purpose and side-effect profile without redundancy. The main action is front-loaded and the read-only clarification is concise and immediately useful.

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 one-parameter read-only tool with an output schema, the description covers what is returned, the side-effect profile, and the resource it applies to. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The only parameter, applicationId, is fully documented in the schema as a 'UUID value wrapper' with a nested value property. Schema description coverage is 100%, so the description does not need to add parameter details; the baseline of 3 applies.

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

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

The description states a specific verb ('Returns') and resource ('suggested opening deposit for a banking application and the reason for that figure'). This clearly differentiates it from sibling tools like banking_confirm_initial_transfer and banking_get_banking_application by focusing on a preview of the suggested deposit amount.

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 this is a preview/suggestion tool, so an agent can infer it should be used when the initial transfer amount needs to be shown before any commitment. It does not explicitly name alternatives or exclusions, but the read-only framing provides clear context for when it is appropriate.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful non-annotation semantics: approval is the partner accepting the corporation, opening happens afterward and can still fail, and an approved application must not be mistaken for an open account. It stops short of mentioning auth or freshness/polling behavior, so 4 rather than 5.

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

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

Three sentences, all front-loaded with the core purpose first, then the state-enumeration rationale. Every sentence earns its place, though the approval-vs-open explanation is slightly repetitive with the earlier 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 explained, and the description still names the state values and the last-four-digits detail. It complements the read-only annotations adequately; only auth/freshness expectations are absent, which is a minor gap.

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

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

Schema description coverage is 100% for the single applicationId parameter, so the schema already documents it. The description adds nothing about the parameter (e.g., which application ID, relationship to the banking application flow). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('reports where this application's deposit account stands') and enumerates the states it returns (queued, opening, open, failed) plus last four digits. It explicitly differentiates itself from the banking application's status, so an agent can pick it apart from banking_get_banking_application 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?

Gives an explicit when-to-use: a caller who wants to tell somebody they can receive money must read this, not the application's status. It names the alternative concept (application status) and the condition that selects this tool over 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 idempotentHint=true and destructiveHint=false, but the description adds valuable depth: it explains the mechanism of idempotency (the stakeholder link is the identity key) and a non-obvious edge case (a corrected owner keeps their correction). This is exactly the kind of context annotations cannot carry.

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 operation and followed by the behavioral nuance. No filler or repetition, though the jargon phrase 'carriable stakeholders' is slightly opaque for an agent parsing intent.

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, and annotations cover the safety profile. The description supplies purpose, idempotency mechanics, and a correction-preservation edge case, leaving it largely complete for a one-parameter mutation.

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 a single parameter at 100% schema coverage, the schema fully documents applicationId, so the baseline is 3. The description adds only the implication that the application must be open, which is marginal semantic value beyond the schema.

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

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

States a specific verb+resource: it carries the company's cap-table stakeholders onto an open application as beneficial owners, so the agent knows both the source and destination of the operation. It is distinguishable from the preview sibling and from hydrate-from-formation by the named domain, though it doesn't explicitly contrast itself with those 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?

Usage is implied rather than stated: 'onto an open application' signals the precondition that an application must already exist and be open, but there is no explicit guidance on when to choose this over banking_preview_cap_table_hydration or banking_hydrate_from_formation. A sibling with a 'preview' name makes the missing routing signal a real gap.

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, and openWorldHint=false. The description adds meaningful runtime behavior beyond those annotations: the write is atomic, records provenance, and does not overwrite applicant-supplied values. It aligns with the annotations rather than contradicting them.

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

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

The description is a single compact sentence with no wasted phrasing. However, its leading clause restates the idempotentHint annotation, and it is arguably too sparse for a hydration operation that has multiple relevant siblings.

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 tool with two required UUID wrapper parameters and close siblings, the description omits its core purpose and alternative-routing information; the behavioral caveat alone is not enough.

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

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

Schema description coverage is 100%, so applicationId and formationId are already documented as UUID value wrappers. The description adds no additional role, format, or constraint information for either parameter, so the baseline score applies.

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

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

States that it idempotently writes values and provenance in one transaction, but does not name the source/target resource or clarify what is being hydrated into what. It also does not distinguish itself from siblings such as banking_hydrate_from_cap_table or banking_preview_formation_hydration.

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 no explicit when-to-use guidance. It does not mention when to choose this over banking_preview_formation_hydration or banking_hydrate_from_cap_table, leaving usage to be inferred from the tool 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value beyond annotations by disclosing an edge-case behavior: the tool is 'unavailable rather than an error when there is nothing to carry.' This is a useful, non-obvious behavioral detail.

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

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

Two concise sentences with no wasted words. The core purpose is front-loaded, and the second sentence adds meaningful behavioral information about read-only status and the no-content edge case.

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

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

With an output schema present and annotations covering the read-only/destructive profile, the description is largely complete. The only minor gap is that it does not explain what 'unavailable' means in practice, but this is a small ambiguity given the rest of the context.

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

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

Schema description coverage is 100%, so the schema already documents companyId as a UUID value wrapper. The description adds no additional parameter meaning beyond implying the company context, so the baseline score of 3 is appropriate.

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

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

The description clearly states that the tool previews which cap-table stakeholders could be carried over as beneficial owners, with a specific resource and outcome. It differentiates from a write operation by explicitly saying 'without writing', but does not explicitly name or distinguish from sibling tools like banking_hydrate_from_cap_table or banking_preview_formation_hydration.

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

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

The description gives clear context: this is a read-only preview used to see potential carryover before actually writing. It does not explicitly state when-not-to-use it or name alternatives, but the 'without writing' and 'read-only' signals make the intended usage reasonably clear.

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

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

The read-only nature is already declared in the annotations (readOnlyHint=true, destructiveHint=false), and the description largely repeats that with 'without writing.' It adds mild behavioral context by noting the preview is what the entry picker uses to detect a genuine warm path, but it does not disclose additional edge-case or state behavior beyond the annotations.

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

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

The description is two sentences and immediately states what the tool does. It front-loads the core purpose and then tucks the reader's usage context succinctly. No redundant passages or filler weaken it.

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 simple two-parameter schema, 100% schema coverage, an output schema, and read-only annotations, the description is nearly complete. It could be slightly richer about what 'carry over' means and how 'genuinely available' is determined, but overall the agent has enough to call the tool correctly.

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

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

Schema description coverage is 100%, so the input schema already documents the companyId and formationId UUID wrappers well. The description adds no parameter-specific meaning, but it does not need to because the structured schema carries that weight. Baseline 3 applies.

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

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

The description states a specific purpose: previewing what a formation would carry over without writing. The phrase 'without writing' meaningfully distinguishes it from hydration tools that perform an actual write. It relies on the domain term 'warm path' but still gives an agent a clear functional picture.

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

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

The description gives a clear usage context: the entry picker should offer the warm path only when this preview confirms it is genuinely available. It implicitly contrasts with a writing/hydrating operation. However, it does not explicitly name sibling alternatives like banking_hydrate_from_formation or banking_preview_cap_table_hydration, so the guidance is contextual rather than enumerated.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond those: the pull-not-push rationale (missed webhooks leave the applicant waiting), the fact that it may advance state once the verdict settles, and why idempotency holds. It omits auth/permission needs and rate-limit 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 core purpose is front-loaded, but the description is padded with self-referential meta-commentary ('A tool, like RefreshOwnerVerification beside it,' and 'The verb heuristic does not know Refresh, so this is stated rather than derived') that explains internal routing heuristics rather than helping the agent invoke the 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 described, and annotations cover the safety hints. Combined with the pull-model explanation and the settled-verdict condition, the description is close to complete for a one-parameter idempotent refresh tool; only explicit selection guidance against sibling reads is missing.

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

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

Schema description coverage is 100% and there is a single applicationId parameter already fully documented by the schema. The description adds no interpretation of the parameter beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource: 're-reads the provider's verification verdict for a submitted application and moves it on when the verdict has settled.' It also names the sibling RefreshOwnerVerification and frames itself relative to it, so an agent can distinguish it from the other banking tools.

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

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

It establishes the pull-over-push usage model and implies repeated polling ('asking again is how the answer arrives'), which is real usage context. However, it never states when to call this instead of the reading tools like banking_get_banking_application, nor any explicit exclusion or precondition.

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

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

Annotations already declare idempotent, non-destructive and closed-world, so the safety profile is covered. The description nonetheless adds useful scope boundaries beyond the annotations: it does not start a verification and it deliberately carries none of the owner's personal data, which is meaningful privacy context for a compliance-adjacent 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?

Three short, front-loaded sentences with no filler: the action is stated first, followed by two crisp scope constraints. Every sentence earns its place.

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

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

An output schema exists, so return values need not be explained, and both parameters are covered. The description supplies action and scope boundaries adequately for a two-parameter refresh tool; only the routing to alternatives is thin.

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

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

Schema coverage is 100%, so both UUID parameters are documented in the schema, giving a baseline of 3. The description maps its two objects to their roles ('one beneficial owner' and 'on a banking application'), which is modest added meaning but no format or constraint detail beyond the schema.

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

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

The description states a specific verb and resource: it re-reads and records the identity-verification outcome for one beneficial owner on a banking application. It also distinguishes itself from the closely-named sibling banking_refresh_application_provider_status by scoping to a single owner rather than the whole application.

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?

Guidance is implied rather than explicit: 'Does not start a verification' tells the agent this refreshes an existing outcome, not initiates one. However, it never names when to reach for this versus siblings such as banking_get_banking_application or banking_refresh_application_provider_status, so the choice is left to inference.

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

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

Beyond the destructiveHint annotation, the description reveals how the sensitive value is handled (secret store, only last four retained), that the response returns nothing, and that the full number is never readable back. This is exactly the irreversibility and privacy context an agent needs.

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

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

Five sentences each carry distinct information: purpose, format, storage, return behavior, and an anti-hallucination guardrail. There is no filler or redundant restating of schema fields.

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 two-parameter mutating tool, the description covers format, privacy, irreversibility, and the missing-EIN edge case, while the output schema handles return expectations. The only notable omission is the behavior when ein is omitted, since the schema marks it optional.

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

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

The description enriches 'ein' beyond the schema pattern by specifying no separators and the storage/truncation behavior. The 'applicationId' parameter is left mostly to the schema's 'UUID value wrapper' description, but the tool description's reference to 'a banking application' provides enough context.

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

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

The opening sentence names a specific verb ('files'), object ('company's EIN'), and target ('banking application'), and adds the exact format constraint. This is enough to distinguish it from similar siblings like banking_set_owner_tax_identifier.

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

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

The description gives a clear contextual trigger and an explicit when-not-to-call rule: if the EIN has been applied for but not received, report that instead of inventing digits. It does not name a sibling alternative, but for this narrow set-style tool the context is sufficient.

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

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

Goes well past the annotations (destructiveHint=true, openWorldHint=false) by disclosing data handling: the number goes to a secret store, only the last four digits are persisted and returned, and the caller should pass it once and never echo it back. That is exactly the privacy/sensitivity context an agent needs before calling a mutation tool on identity data.

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

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

Three tight sentences, front-loaded with the action and the eligibility condition, followed by the prerequisite and then the sensitive-data handling rule. No filler, and the most important operational warning comes last where it is still prominent.

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 helpfully notes the response only echoes the last four digits. Annotations cover the safety profile. The only gap is not naming the tool that records the document kind/country/expiry/state, which the agent must locate on its own.

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 67% and documentNumber has no schema description, but the description identifies what that parameter carries (a passport or driver's license number) with constraints implied by the source documents. The two ID parameters are only wrappers with schema descriptions, so the description's added value is mainly on the one undocumented parameter.

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 (files the document number for a beneficial owner) plus the exact scope: passport or US driver's license, on a banking application, for an owner with no SSN or ITIN. This cleanly separates it from the sibling banking_set_owner_tax_identifier, which covers the SSN/ITIN case.

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

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

Gives a clear selection condition (owner has no SSN or ITIN) and a prerequisite sequence (record the document's kind, issuing country, expiry, and issuing state on the owner first). It does not name the alternative tool an agent should use when the owner does have an SSN/ITIN, so the routing is implied rather than explicit.

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

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

Goes well beyond the annotations: it discloses that the full number is routed to a secret store while only the last four digits are persisted and returned, that a kind mismatch is refused, and that the value must be passed exactly once and never echoed back. These are non-obvious security and validation behaviors an agent cannot infer from destructiveHint/openWorldHint.

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

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

Four sentences, front-loaded with purpose before guidance, and each sentence carries operative information. It is slightly dense with stacked imperatives ('never guess it, never read it back...'), 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?

For a mutating tool with annotations, a nested-object schema and an output schema, the description covers what matters: the prerequisite for completion, the SSN/ITIN classification rule, and the secret-handling contract. Nothing an agent needs to call it correctly is missing.

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

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

With schema coverage at 50%, the description compensates usefully by explaining the kind parameter's semantics that the bare enum labels do not convey (ITIN starts with 9, SSN never does, mismatch refused). It adds little for ownerId/applicationId, but those are self-describing UUID wrappers in the schema.

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

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

States a specific verb and resource — filing one beneficial owner's SSN/ITIN against a banking application — with clear scope ('one', 'beneficial owner'). This is readily distinguishable from siblings like banking_set_application_ein (company EIN) and banking_set_owner_identity_document_number (a different document type).

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 instructions: ask the person which of SSN/ITIN they hold, pass it as kind, and the prerequisite that each assessed owner needs one for completion. It does not, however, name a sibling alternative for cases where the identifier lives elsewhere (e.g. formation_set_shareholder_tax_identifier).

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 are thin (openWorldHint and destructiveHint only), so the description carries most of the behavioral disclosure. It adds a valuable business rule about refusing a second undecided application and explains the data source behavior for warm versus cold paths. However, it does not disclose what is persisted, whether side effects occur immediately, or any permission requirements. There is no contradiction with the destructiveHint=false annotation.

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 three short sentences with no filler. It front-loads the purpose, then adds the critical uniqueness constraint, then explains the path parameter compactly. Every sentence contributes operational information an agent needs.

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

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

The description covers the core starting semantics and the main path distinction, and an output schema exists to document return values. However, it leaves an agent guessing about the correct combination of parameters, especially whether formationId is required for WARM_FORMATION, and it could usefully reference checking for an existing undecided application before calling.

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 67% and the ID parameters are only documented as 'UUID value wrapper', so the description is needed to add real meaning. It does explain both enum values of the path parameter in useful terms, but it never explains the semantic role of companyId or formationId, and notably does not say that formationId is tied to the WARM_FORMATION path.

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 ('opens a business account application') and identifies the resource (a company's business account application). It also differentiates this from the many sibling banking/application tools by framing it as the starting operation and by naming the unique one-undecided-application constraint.

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

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

The description gives clear conditional guidance for choosing the path parameter: WARM_FORMATION when the company was formed with Lovie and data can be carried over, COLD_MANUAL when the applicant enters answers manually. It also warns that starting a second undecided application is refused, though it does not explicitly point to alternatives such as banking_update_banking_application for existing applications.

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 annotations only covering destructiveHint and openWorldHint, the description carries substantial extra burden and delivers: the freeze is one-way, subsequent writes are refused with ErrApplicationFrozen, blocking sections are returned instead of a bare failure, and re-calling after a correction resubmits. This is exactly the behavioral context an agent needs before invoking a mutation.

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 behaviorally useful content is front-loaded and dense, but the description also contains design-rationale asides aimed at a reviewer rather than an agent ('Being option-less made it look like an ordinary field write') that do not help invocation and dilute the signal.

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 one-parameter mutation tool with annotations and an output schema, the description is nearly complete: safety profile, one-way freeze semantics, error behavior, and the correction exception are all covered. Return-value detail is not needed because an output schema exists.

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

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

There is a single applicationId parameter with 100% schema description coverage, so the schema already documents it. The description adds no additional meaning about this parameter, making the baseline 3 appropriate.

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

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

The description names the specific action (submit/freeze a banking application) and describes its effect precisely, including the one-way freeze and the ErrApplicationFrozen consequence. It implicitly separates itself from an 'ordinary field write', though it never names the sibling tools (e.g. banking_update_banking_application) that an agent might confuse it with.

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

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

It gives clear context for use ('filling in and submitting an application is what an agent is for here') and a notable exception for partner-requested corrections that allow resubmission. What is missing is an explicit when-not statement or a named alternative for the cases it is not suitable 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses return format (official title and matched words, best match first), failure behavior (returns nothing rather than inventing a code when too short or outside the covered set), and a compliance guardrail (never apply without person confirmation). This is rich behavioral context that annotations alone cannot provide.

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

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

Four sentences, each earning its place: purpose, return format, failure mode, and compliance guardrail. The description is front-loaded and contains no filler or redundant restatement of the tool name.

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 two-parameter suggestion tool with an output schema and read-only annotations, the description covers purpose, result content, failure mode, and a critical safety rule. The only meaningful gap is the undocumented limit parameter, and it does not mention the similar formation_suggest_naics_codes sibling.

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

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

The description adds plain-language semantics to businessDescription by framing it as a description of what a business does, but it never explains the optional limit parameter. With only 50% schema coverage and no limit description in the schema, an agent must infer that limit caps the number of candidates, so the compensation is 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 states a specific verb and resource: 'Suggest NAICS industry classification codes from a plain-language description of what a business does.' It also names the concrete output (candidate codes with official title and matched words), and the banking compliance warning distinguishes it from similar formation/suggestion tools.

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

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

The description gives clear context for when to use the tool: converting a plain-language business description into NAICS candidates, with a banking compliance framing. It does not explicitly name alternatives or exclusions, but the intended use case is unambiguous.

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

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

Annotations only supply openWorldHint=false and destructiveHint=false, so the description carries the burden and does add real, non-obvious behavior: updates are mask-scoped partial writes, and every masked path writes USER provenance so corrections re-attribute the value. That provenance side effect is exactly the kind of trait an agent cannot infer from the schema. It stops short of auth requirements, error behavior for non-correctable fields, or whether unmasked fields are left untouched.

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

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

Two sentences, zero filler, and the mask mechanic plus its side effect are front-loaded. For a tool with a deeply nested payload it is arguably too terse, but there is no waste to trim.

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. The description covers the two most important non-obvious facts (partial-mask update and provenance re-attribution), but omits correctable-field constraints and error/permission behavior for a very complex nested-entity mutation, leaving noticeable gaps.

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

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

Schema coverage is 50%. The description meaningfully extends the updateMask parameter (the schema only says 'Comma-separated field paths') by explaining that each path also writes USER provenance, and 'takes a FieldMask' signals the update semantics. However, it says nothing about the large nested 'application' object, so half the parameter surface remains 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 leans on the tool name ('UpdateBankingApplication') rather than stating the operation plus resource in its own words, and it jumps straight into the FieldMask mechanic. It implies partial-update semantics, which is useful, but it never scopes what a banking application contains or how this differs from siblings like banking_upsert_beneficial_owner or banking_confirm_extracted_value.

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

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

The phrase 'correcting a carried-over value' hints at one use case, but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives. With a dozen banking_* siblings that mutate or hydrate the same application, this gap matters.

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 only openWorldHint=false and destructiveHint=false in annotations, the description carries meaningful extra burden and delivers: a rejected request returns INVALID_ARGUMENT and writes nothing, plus the rationale for why ssn_last4 cannot be accepted. It does not explain how a given owner is matched for update versus insert, which is the remaining behavioral 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?

The action is front-loaded in the first sentence and the constraint follows immediately. The final sentence is justificatory but earns its place by explaining the failure model 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 no explanation, and the critical ssn_last4 gotcha is covered. However, for an upsert tool whose owner.id is optional, the description never says what key determines add-versus-update, which is the most important thing an agent needs before calling it.

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

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

At 50% schema description coverage across a ~30-field nested owner object, the description compensates for exactly one high-risk field: it tells the agent that ssn_last4 must be omitted. The remaining nested fields (id, kind, verification fields, and how they drive upsert matching) get no added meaning, matching the baseline for partial 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 states a clear verb+resource: it 'adds or updates one beneficial owner,' and it operationally distinguishes itself by routing SSN-last4 handling to SetOwnerTaxIdentifier. It stops short of differentiating the upsert itself from adjacent sibling operations like banking_set_owner_identity_document_number, so it is clear but not fully sibling-aware.

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 explicit when-not rule with a named alternative: if the owner carries ssn_last4, the call is refused and the agent must use SetOwnerTaxIdentifier instead. That is real routing guidance, though there is no broader statement about when to upsert versus hydrate/refresh flows.

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 clearly states the operation is destructive ('deletes every stakeholder'), but the annotations declare destructiveHint false. This is a direct contradiction, making the behavioral transparency misleading. The description adds the important detail of 'single DB-level operation' but the annotation conflict overrides that.

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, each adding value: the first defines the exact action and scope, the second explains its intended usage. No filler or redundant content.

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

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

The description covers the essential aspects: what it does, scope, and use case. It does not explain irreversibility, permissions, or downstream effects, but given the simple single-parameter signature and presence of an output schema, this is mostly adequate. The annotation contradiction reduces trust but not completeness per se.

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

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

Schema description coverage is 100% with companyId documented as 'UUID value wrapper.' The description adds no additional parameter semantics beyond what the schema provides. Baseline of 3 is appropriate because the schema fully covers the single parameter.

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 'deletes' and clearly identifies the resource 'every stakeholder of a company'. It distinguishes itself from sibling tools like cap_table_delete_cap_table_stakeholder by emphasizing the bulk, all-stakeholders scope and single DB-level operation.

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 a clear use case: 'Used by the "replace cap table" import flow.' This gives context for when to invoke this tool versus the singular delete alternative. However, it does not explicitly list exclusions or alternative tools for partial deletes, but the context is sufficient.

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 destructiveHint=true and openWorldHint=false; the description goes well beyond by disclosing that the action is irreversible ('CANNOT be undone'), writes the cap-table of record, and persists snapshots/conversions. That is exactly the behavioral context an agent needs before a destructive 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 tightly written sentences, each earning its place: purpose/effects, trigger + irreversibility + confirm prompt, and the alternative. Front-loaded with the core action and 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?

An output schema exists so return values need no explanation, and the destructive semantics are fully covered. The only gap is the undocumented optional parameters, which leaves an agent unable to reason about inputs like newMoneyRaise or preMoneyValuation.

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 only 25% across 8 parameters, and the description explains none of the meaningful inputs (newMoneyRaise, preMoneyValuation, targetOptionPoolPct, optionPoolBasis, recordedHistory, carryForwardUnwired). With low coverage, the description should compensate but does not, leaving most inputs 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?

States a specific verb+resource ('CloseCapTableRound PERMANENTLY closes the round') and enumerates the concrete effects: calc engine run, SAFE conversions + ownership snapshots persisted, round flipped to CLOSED. This clearly distinguishes it from siblings like cap_table_preview_close_cap_table_round or cap_table_reopen_cap_table_round.

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

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

Gives explicit trigger phrases ('close the round', 'make it permanent', 'finalize the round') and names the alternative (PreviewCloseCapTableRound) with the exact condition that selects it. It also advises confirming with the user first, which is real usage 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?

Even though annotations flag destructiveHint=true, the description goes far beyond that: it explains exactly what a signed FAST writes to the cap table (advisor on register as stakeholder, option holding with equity percentage and fixed 24-month/3-month cliff vesting), that an unsigned FAST grants nothing, and that a name mismatch adds a silent second, equity-free stakeholder row that hides in ownership views but counts in stakeholder counts. This is the level of disclosure a mutation tool needs.

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

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

Front-loaded with the core action, then the critical signed_at warning before any secondary detail; every sentence carries real behavioral content. It is dense and long, and the all-caps emphasis is heavy, but nothing reads as filler.

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

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

For a 10-parameter, nested-object mutation tool with an output schema present, the description covers the branches an agent must get right (draft vs. signed, party matching) and the parameter formats the schema omits. Return values are left to the output schema, which is appropriate.

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

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

Schema coverage is only 30%, so the description must compensate and does: it defines signed_at (a declaration, not a date field), advisor_equity_pct format ('0.50', trailing % accepted), effective_date as the vesting start in YYYY-MM-DD, and the PARTY exact-name matching rule. This is substantial added meaning over the bare 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+resource (records a non-SAFE agreement) and enumerates the concrete agreement types (option, RSU, RSA, FAST advisor agreement, board consent). Distinguishes itself from siblings like cap_table_import_safe and cap_table_record_cap_table_investment by scoping to non-SAFE equity agreements.

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

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

Explicitly defines when to set signed_at versus leaving it empty ('the safe choice'), and instructs to call GetListCapTableStakeholders first and pass stakeholder_id when the advisor is already on the register. The rule 'set it ONLY when the person tells you the agreement has been signed' directly resolves the branch point.

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 explicitly states 'Writes.' in a terse but clear manner, compensating for the absence of a readOnlyHint annotation. It also discloses a key behavioral trait: a new round starts OPEN and holds no capital, which is not apparent from annotations or the schema. This adds meaningful context about the tool's side effects. However, it doesn't mention any other side effects (e.g., whether it returns the created round verbatim), but given the output schema exists, that's less critical.

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 three sentences, each earning its place. The first sentence states the core purpose, the second is a minimal 'Writes.' that conveys an essential fact, and the third clarifies the initial state and scope. There is no fluff, and the key information is front-loaded. This is an excellent example of concise, structured description.

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

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

Given the tool's complexity (a nested 'round' object with 13 fields, most undocumented in the schema), the description leaves the agent without guidance on what to supply. It doesn't explain the meaning of 'pastRound', the required 'companyId', or what fields like 'isPriced' or 'pricePerShare' represent. While the output schema exists, the input side is severely under-specified. The description could have provided field-level hints or examples, but it doesn't, making the tool hard to invoke correctly without external knowledge.

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%: the schema provides no descriptions for most fields (e.g., name, status, isPriced, optionPoolPct, etc.). The description does not compensate at all. It never mentions the 'round' object or its required fields, nor the 'pastRound' parameter. For an agent to correctly populate the complex nested round object, it would have to infer from field names, which is error-prone. The description adds zero value for parameter understanding.

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

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

The description opens with a specific verb and resource: 'Opens a new funding round'. It further explains what a round is ('the container investors and their agreements are attached to'), which is central to understanding the tool's role. It also explicitly distinguishes from close operations by stating 'It does not raise money or close anything', clearly separating it from sibling tools like cap_table_close_cap_table_round.

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

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

The description clearly implies when to use this tool: when creating a new funding round. It adds 'It does not raise money or close anything: a new round starts OPEN and holds no capital until investors are added to it', which tells the agent not to expect this to handle investor additions or closing. While it doesn't name specific alternative tools, the negative statements effectively route the agent away from close/update tools. This is useful but not as explicit as naming a specific sibling.

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 clearly discloses key behavioral traits beyond the annotations: it does not create holdings, does not appear in the investor pipeline, and warns that duplicating a name results in duplicate register entries. The annotations only provide openWorldHint=false and destructiveHint=false, so the description carries the main behavioral burden and does so effectively, though it doesn't address side-effects or error cases.

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

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

The description is longer than average but every sentence contributes substantive guidance. It's front-loaded with the core scoping statement, then gives exclusions and a reliable alternative. There is minor redundancy between the two 'do not call the following' sentences, but overall it is well-structured and efficient for the complex decision it supports.

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 cap table tool with a deeply nested single parameter, the description is remarkably complete. It not only explains what the tool does but also the business context (pipeline, holding, register) and the correct operational sequence. The output schema exists to explain return values, so the lack of return-value detail is not a gap. An agent has enough context to call this tool correctly.

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

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

Since the schema description coverage is 0%, the description must compensate for the single nested parameter. It does name the identity subset (name, type, email, metadata), which adds meaning, but it does not explain the full set of fields such as title, userId, address, companyId, etc., nor the enum values. The 'identity only' framing is useful, but the description leaves some parameter-level detail unstated.

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 action and scope: 'Adds a stakeholder IDENTITY ONLY (name, type, email, metadata).' It explicitly distinguishes this from holding/security creation, and the caveat about not appearing in the pipeline further disambiguates it from sibling tools like RecordCapTableInvestment. The agent can immediately understand what this resource is and is not.

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 explicit when-to-use and when-not-to-use guidance: 'Use this tool only for a party who is genuinely meant to have no holding at all.' It names the alternative tool (RecordCapTableInvestment) and instructs on the correct call order, including how to pass a previously returned stakeholder_id. This is textbook usage routing.

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

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

Annotations already flag destructiveHint=true, and the description simply says 'removes', adding no new behavioral context. It does not disclose permanence, cascading effects, or any special permissions, which are valuable for a destructive operation.

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 extremely short (six words), which is concise, but the content is largely a restatement of the tool name and adds little informational value. It is not 'appropriately sized' because it under-specifies the operation.

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 destructive delete operation, the description is severely lacking in contextual detail. It does not explain what 'removing an agreement' entails (e.g., irreversibility, associated records, permission requirements), and the available annotations do not compensate for this gap.

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

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

Schema description coverage is 100% (though the 'UUID value wrapper' descriptions are minimal), so baseline is 3. The tool description adds no parameter meaning beyond what the schema provides, but the parameter names and types are fairly self-explanatory given the tool name.

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 'DeleteCapTableAgreement removes an agreement' is essentially a tautology of the tool name and title. It states the action verb 'removes' and resource 'agreement' but adds no specificity or differentiation from sibling tools like deleting a round or stakeholder.

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 is provided on when to use this tool versus alternatives. It does not mention prerequisites, side effects, or contrast with related cap_table operations, leaving the agent without decision support.

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 destructiveHint annotation by specifying the cascading effect ('plus its round-scoped securities/agreements/snapshots') and the rejection condition with error type ('FailedPrecondition'). This discloses important behavioral traits that annotations alone do not provide.

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 that front-load the action and scope, with no wasted words. It efficiently covers purpose, applicability, and limitations.

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 deletion tool with an output schema and two simple parameters, the description covers the essential context: what is deleted, what is rejected, and the permanent nature. It does not need to explain return values because the output schema exists, and the annotations cover safety.

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

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

The input schema already describes both parameters as 'UUID value wrapper' with 100% coverage, so the description adds minimal parameter-specific meaning. It implicitly connects roundId to the SAFE round but does not elaborate beyond the schema.

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

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

The description clearly states the tool's function: 'permanently removes an unpriced SAFE round (open or light-closed) plus its round-scoped securities/agreements/snapshots.' This specifies the exact resource and action, and distinguishes it from sibling tools like close_cap_table_round or delete_cap_table_agreement.

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

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

The description provides explicit conditions: it is for unpriced SAFE rounds in open or light-closed states, and 'Priced / engine-closed rounds are rejected (FailedPrecondition).' This clearly tells the agent when to use the tool and when not, though it does not explicitly compare with alternatives.

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

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

Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds minor value by specifying it removes 'one holding', implying a single entity deletion, but it does not disclose irreversibility, side effects on related data, or permission requirements.

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 one concise sentence, immediately front-loaded with the action ('removes'). It wastes no words and is easy for an agent to parse.

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

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

Despite having an output schema and annotations, the description is very minimal for a destructive operation. It lacks contextual information such as what happens to associated holdings, whether deletion is permanent, or any preconditions. The complexity is low, but the absence of behavioral context makes it incomplete for safe invocation.

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

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

Schema description coverage is 100% (both parameters have descriptions like 'UUID value wrapper'), so the schema carries the parameter meaning. The description adds no additional semantics beyond what the schema provides, keeping the baseline score at 3.

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

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

The description clearly states the action ('removes') and the specific resource ('one holding'), which is more precise than the title. It distinguishes this from sibling delete tools (e.g., delete_cap_table_agreement, delete_cap_table_round) by focusing on the security/holding entity.

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 is provided on when to use this tool versus alternatives, nor any prerequisites or exclusions. Unlike examples like 'use search_calls_extensive instead', there is no mention of alternative tools or specific conditions for deletion.

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