Shareflo

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

Annotations only supply destructiveHint=true, so the description carries most of the burden and does add real value: the unlock_shareflo prerequisite and the fallback behavior when stakeholder is omitted. It does not explain why the operation is flagged destructive, what permissions are needed, or whether the addition is reversible, leaving some gaps.

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 core action, then the conditional behavior and the prerequisite. No filler or redundancy; every sentence carries distinct information.

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

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

For an 8-parameter mutation tool with no output schema, the description covers the essential prerequisite and the key branching behavior. It stops short of describing permissions, the meaning of the destructive hint, or side effects on the stakeholder's existing representatives, which would round out a write operation.

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 all eight parameters, including the omit-behavior for stakeholder and the mutually exclusive co_permission/sh_permission fields. The description's note that omission yields a 'company-level cap table administrator' adds minor nuance but largely restates what the schema says; baseline 3 applies.

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

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

States a specific verb and resource ('Adds a representative (user)') plus the object of management ('a stakeholder's account'), which clearly distinguishes it from siblings like create_stakeholder or get_representatives. An agent can identify the operation without opening the schema.

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

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

Gives a hard precondition ('Requires unlock_shareflo to have been called first') and a conditional usage rule ('If the stakeholder field is omitted, the representative is added as a company-level cap table administrator'). It does not name alternative tools for adding users, but the context and exclusions it does provide are 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?

Beyond the sparse annotations (destructiveHint=false, title only), it discloses the important two-phase behavior: this only creates a proposal and nothing changes until confirm_action, and it names the unlock_shareflo lock prerequisite. It stops short of explaining proposal lifecycle details such as how to review the pending proposal or that it can be discarded.

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

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

Three sentences, front-loaded with the action and scope, then omission semantics, then the proposal/confirm and unlock caveats. Every sentence carries information an agent needs; nothing is 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?

For a 10-parameter mutation tool with no output schema, the description covers purpose, scope, omission semantics, the lock prerequisite and the confirm gate. The main remaining gap is that it never indicates what the proposal response/UID looks like even though there is no output schema documenting it.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds a genuinely useful cross-cutting rule beyond the per-parameter text — "Give only the terms that change; omitted terms keep their current value" — and scopes the call to a single holding. It adds no syntax or format guidance beyond what the schema already carries.

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?

"Proposes changing the vesting terms of one holding, or an option holding's exercise price" gives a specific verb, resource and scope, and clearly separates it from siblings like stop_vesting and exercise_options (which are true mutations, not proposals). An agent can identify the tool without opening the schema.

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

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

Explicitly states the omission semantics ("Give only the terms that change; omitted terms keep their current value") and the prerequisite "Requires unlock_shareflo to have been called first", plus the workflow step "nothing changes until confirm_action". It does not, however, say when to prefer this over the sibling stop_vesting for removing vesting entirely, or how a proposal is later inspected/discarded.

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 destructiveHint=false, so the description carries the real behavioral burden: it is a two-phase operation ('nothing changes until confirm_action'), requires an authenticated unlocked session, and explains how replaces_proposal_uid supersedes an old proposal. This is consistent with the safe/non-destructive 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?

Front-loaded with the core action and scope, then prerequisites. It is dense at six sentences and slightly repetitive about vesting/partial cancellation, but nearly every clause carries operational information rather than filler.

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

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

With no output schema, the description still gives an agent everything needed to call correctly: the proposal-only nature, the confirm_action follow-up, the unlock prerequisite, the stop_vesting dependency, and the replace-a-proposal mechanism. Nothing material is missing for a six-parameter mutation-like tool.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds logic the field-level text doesn't fully convey: whole-holding cancellation is always permitted while partial cancellation depends on vesting state, and take_from only matters when the holding is partly vested and vesting has stopped. That conditional framing adds real meaning about how quantity and take_from interact.

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 ('proposes cancelling shares or options from one holding') with concrete examples (leaver forfeiture, company cancellation), and clarifies the tool's output is a proposal rather than a mutation. An agent can distinguish it from siblings like stop_vesting or confirm_action immediately.

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

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

Explicitly states when partial cancellation is allowed and when it is not, names the alternative (use stop_vesting first), and gives the required precondition (unlock_shareflo must have been called). This is textbook when/when-not/alternative 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 only supply destructiveHint=true; the description carries the rest and does so well, disclosing the authorization prerequisite (requires unlock_shareflo first), the runtime failure modes ('may refuse it if the user lacks permission or the cap table changed since the proposal was made'), and the one-proposal-per-call constraint. This is substantially more than the annotations 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?

Front-loads the action and its scope before the conditions, and every sentence carries a distinct constraint (provenance, approval gate, alternatives, failure modes, prerequisite). The second sentence's 'on your own initiative / hasn't seen' clauses slightly overlap, adding modest redundancy to an otherwise tight definition.

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

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

For a destructive, output-schema-less mutation tool, the description covers provenance of the input, the approval gate, prerequisites, and refusal conditions. It stops short of saying what a successful confirmation returns or how partial failures surface, which an agent invoking a cap-table commit would benefit from knowing.

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 one parameter and 100% schema coverage, the baseline is 3, but the description adds meaning by naming all the upstream tools that can produce a valid proposal_uid and enforcing 'one proposal per call'. It does not add format or validation details 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 and resource ('Commits one Open action proposal to the cap table') and immediately enumerates the sibling tools whose output it consumes (create_holding, stop_vesting, exercise_options, etc.). An agent can distinguish this from discard_action or the individual proposal-creating tools without opening any schema.

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

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

Gives explicit when-to-use conditions (user has seen and approved the terms in their latest message), explicit when-not conditions ('Never call it on your own initiative', not for unseen proposals, not for multiple proposals on a single approval), and names the alternative path for changed terms (create a new proposal with replaces_proposal_uid).

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=false, so the description carries real weight by disclosing that it only creates a proposal and nothing changes until confirm_action, the unlock prerequisite, the one-for-one/same-stakeholder mechanics, the new holding's tax scheme of None, and that the original holding is reduced.

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

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

The purpose and key constraints are front-loaded, and each sentence conveys a distinct rule (target validity, vesting defaults, partial conversion, proposal-only nature, prerequisites). It is dense but essentially waste-free, though longer than strictly minimal.

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 an 11-parameter mutation-style tool with no output schema and only a destructiveHint annotation, the description covers workflow prerequisites, constraints, partial-conversion rules, and the proposal/confirm lifecycle. An agent has what it needs to call it correctly without the output 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%, so the 3 baseline applies, but the description adds interpretive value beyond the schema: omitting the vesting schedule means no vesting, and partial conversion is only possible once vesting is stopped. It does not enumerate every one of the 11 parameters, so it improves on but doesn't fully replace 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 ('Proposes converting shares from one holding into a different share class of the same company'), including the one-for-one and same-stakeholder constraints. It is easily distinguished from siblings like transfer_shares, exercise_options, and create_holding.

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 names explicit alternatives and preconditions: use stop_vesting first for partial conversions, unlock_shareflo must be called first, and confirm_action is required to apply. It also states a clear exclusion (shares can't convert into options, and options can't be converted).

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 destructiveHint=false and a title in annotations, the description carries the burden well: it discloses that the output is a proposal (not a committed award), requires prior unlock_shareflo, and must be human-approved before confirm_action. This is exactly the behavioral context an agent needs to avoid prematurely finalizing an award.

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, with the workflow front-loaded (create proposal → present → confirm). No filler or redundancy.

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

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

For a 21-param, no-output-schema, mutation-style tool, the description covers the dependency (unlock_shareflo), the human-in-the-loop requirement, and the correction path (replaces/new proposal). The 'present the returned proposal' line also implicitly covers how to use the return value.

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

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

Schema description coverage is 100% and each of the 21 params is already documented in-schema, including the override pattern. The description only adds the meta-point that defaults are filled in automatically, which is a modest addition over the schema baseline.

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 action ('creates an award proposal') and frames it as the first step of allotting/awarding shares or options. This clearly distinguishes it from create_instrument, create_stakeholder, and confirm_action in the sibling set.

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 sequencing: call only after unlock_shareflo, present the returned proposal to the user, call confirm_action only after active approval of that exact proposal, and create a new proposal if alterations are wanted. When-to-use and the flow relative to alternatives are fully specified.

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 destructiveHint=true, and the description usefully adds the unlock_shareflo gating requirement, which is real behavioral context beyond the structured fields. However, it never explains what the operation alters or why a creation is flagged destructive, nor what matters about the unlocked session, so the added value is modest.

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. The core purpose leads and the prerequisite follows immediately, so both facts an agent needs are front-loaded and no sentence is redundant.

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

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

For an 11-parameter mutation with no output schema, the description covers purpose and the unlock prerequisite but omits what is returned (e.g. the new instrument identifier) and any hint about the destructive flag's implication. Combined with 100% schema coverage the gaps are not fatal, but they are visible for a create operation.

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 11 documented parameters, 3 enums, and conditional mandatory rules (nominal_value/currency for Shares, exercise_price/currency/underlying_share_class for Options), so the schema carries the semantics. The description contributes nothing parameter-specific beyond the subtype vocabulary, which is the correct baseline of 3.

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

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

States a specific verb ('Creates') and resource ('a new instrument') and scopes it ('for the company'), then enumerates the concrete subtypes (share class, option class, or other) that mirror the instrument_type enum. This clearly separates it from sibling creators like create_holding and create_stakeholder without naming them.

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

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

Gives an explicit prerequisite: unlock_shareflo must have been called first, which directly ties it to a named sibling tool and prevents a failed invocation. It stops short of stating when NOT to use it or naming alternatives such as get_instruments for inspection, so it falls short of the full when/when-not bar.

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 destructiveHint=true plus a title, so the description carries real weight and delivers: the unlock_shareflo precondition, the required follow-up prompt, and the downstream representative path. It does not disclose duplicate-handling, idempotency, or what identifier/response comes back after creation, which matters for chaining into add_representative.

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

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

Three short sentences, zero filler, and the operation description is front-loaded before the prerequisite and the follow-up instruction. Every clause carries actionable information for the caller.

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

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

With no output schema, the description would ideally say what a successful call returns (e.g. the new stakeholder identifier needed by add_representative), but it does cover the precondition and the immediate next step. For a 10-parameter creation tool this is close to complete, with the response contract as the only notable 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 schema already documents all ten parameters including the enum values, employee-only fields, and the email auto-representative behavior. The description adds no parameter-level detail beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Creates a new stakeholder') and goes further by defining the domain term in parentheses ('holder of an instrument'). It is clearly distinguishable from read-oriented siblings like get_stakeholders, though it never names a sibling directly to route between competing creation tools such as create_holding or add_representative.

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 hard prerequisite ('Requires unlock_shareflo to have been called first') and a post-call workflow step (ask about registering a representative user). It lacks explicit when-not guidance, e.g. when to use add_representative directly instead of relying on the email auto-creation path, so it stops short of the top band.

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 destructiveHint=false; the description adds the substantive context: no cap-table mutation, permanent unconfirmability, who is permitted to act, and a gating state prerequisite. These are exactly the traits an agent needs and cannot get from the 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?

Four tight sentences, front-loaded with the action and its effect, then alternatives, permissions and prerequisite. Every sentence carries distinct information with no filler.

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

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

For a one-parameter, non-destructive action with no output schema, the description covers effect, irreversibility, alternative path, authorization and prerequisite gating. There is nothing an agent needs in order to invoke it correctly that 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 the only parameter is already documented as 'UID of the Open proposal to discard. One proposal per call.' The description restates the single-proposal-per-call limit but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Discards one Open action proposal') with scope ('one', 'Open') and the resulting state ('so it can never be confirmed'). This distinguishes it cleanly from confirm_action and from re-calling the original proposal tool.

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

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

Explicitly says when not to use it and what to do instead ('To correct a proposal, don't discard it: call its tool again with replaces_proposal_uid'), plus the authorization set (requester, Admin, Manager) and the prerequisite ('Requires unlock_shareflo to have been called first'). Nothing about routing is left to inference.

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

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

Annotations supply only destructiveHint=false, so the description carries the real behavioral burden and does: it discloses the proposal-only, no-side-effects-until-confirm_action semantics, the vesting gate, the quantity cap, the tax-scheme carryover, and the unlock_shareflo dependency. These are exactly the operational traits an agent needs before calling a mutation-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?

Four sentences, each carrying distinct load: the action, the outcome, the preconditions, and the confirm gate. The most decision-relevant constraint (proposal-only) and the dependency chain are front-loaded rather than buried.

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

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

For a 5-parameter tool with no output schema, the description covers preconditions, side effects, and correction semantics thoroughly. The one small gap is that it never says what the call returns (e.g., a proposal UID) even though replaces_proposal_uid presupposes the agent can obtain an open proposal's UID.

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 holding_uid, quantity, exercise_date, notes, and replaces_proposal_uid are already documented in the schema. The description restates the vested-quantity constraint but adds no syntax, format, or edge-case detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The opening sentence names a specific verb (proposes exercising) and resource (options from one option holding), and the follow-up explains the resulting share conversion and tax treatment. An agent can distinguish this from siblings like convert_share_class or transfer_shares without opening any schema.

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

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

It states explicit prerequisites and routes to alternatives by name: stop_vesting must have run first if a vesting schedule exists, unlock_shareflo must have been called, and confirm_action is required before anything takes effect. It also covers the correction path via replaces_proposal_uid, leaving no when-to-use ambiguity.

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 readOnlyHint=true, so the description carries the rest and does so well: it discloses the unlock_shareflo prerequisite, the one-line-per-holding return shape with holding_uid, and the disambiguation protocol when several records match. These are behavioral traits well beyond what the annotation provides.

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

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

Front-loaded with the core purpose and the holding_uid rationale, and every sentence is relevant. However, the multi-match disambiguation guidance is spread over two sentences that partially restate each other ('when several records match, the reply lists them' vs. 'when more than one holding matches... ask which one'), which is mild 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?

With no output schema, the description compensates by describing the return shape, and it covers the prerequisite, the filter matrix, and the ambiguity-handling flow. An agent has everything needed to select and call this tool correctly without opening any 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?

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description still adds combination semantics the schema does not state, namely that the two filters are combinable and that omitting both returns all holdings, which is genuine meaning beyond the field-level text.

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

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

States a specific verb and resource ('Lists the confirmed holdings of shares, options and other instruments in the company') with the scope of what each line contains. It is clearly distinguishable from sibling readers such as get_instruments and get_stakeholders, and it explicitly ties itself to the share-action tools as the source of holding_uid.

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?

Spells out when to use each filter mode: filter by stakeholder, by instrument, or both, and with neither it returns everything. It names the six downstream tools that consume the returned holding_uid, establishing why and when an agent should call it, and states the unlock_shareflo prerequisite.

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

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

Annotations declare readOnlyHint=true, so safety is covered; the description adds genuinely useful behavioral context beyond that by disclosing the unlock_shareflo sequencing dependency. It does not describe failure behavior when the prerequisite is missing, nor pagination or return format.

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

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

Two short sentences, zero filler, with the scope statement front-loaded and the prerequisite immediately after. 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?

No output schema exists, so the description carries some burden for return values; it does characterize the result as all share instruments/share classes, which is adequate for a zero-parameter read. The only gap is the absence of failure/pagination behavior, which is minor for this tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameters for the description to explain, and it correctly uses its words on scope and prerequisites instead.

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) and resource (all share instruments / share classes) scoped to 'this company', with a clarifying parenthetical. It does not explicitly contrast itself with siblings like get_holdings or create_instrument, but the resource is distinctive enough that an agent can identify it.

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

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

Provides a concrete prerequisite: 'Requires unlock_shareflo to have been called first', naming a sibling tool and the condition for calling it. It stops short of stating when NOT to use it or what happens if the prerequisite is unmet (error vs empty result).

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 readOnlyHint=true, and the description adds meaningful behavior beyond that: the default scoping when the parameter is omitted and the mandatory unlock_shareflo prerequisite. It does not describe return structure or pagination, but the added operational context is substantive.

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

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

Three short sentences, each front-loaded and earning its place: what is returned, the omitted-parameter default, and the prerequisite. 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?

With no output schema, the description carries the return-value burden and does state the returned content (representatives and permission levels). Combined with the default-scoping note, prerequisite, and readOnly annotation, an agent has enough to call it correctly; only finer return-format detail is absent, which is minor for a simple read tool.

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

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

Schema coverage is 100%, so the 'stakeholder' filter is already documented; baseline is 3. The description goes beyond the schema by explaining the semantics of omitting the parameter (falls back to company-level cap table administrators), which is not captured anywhere 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 ('Returns') and resource ('representatives (authorised users) and their permission levels'), making the output content clear. It is distinguishable from the get_* siblings by resource, but does not explicitly name or contrast any sibling tool.

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

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

Provides a clear usage condition ('If no stakeholder is specified, returns company-level cap table administrators') and a hard prerequisite ('Requires unlock_shareflo to have been called first'). It stops short of naming alternative tools, but the context for calling it is explicit.

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

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

Annotations declare readOnlyHint=true, so the safe-read profile is already covered. Beyond that, the description adds the stateful prerequisite (unlock_shareflo must run first), which is exactly the kind of sequencing context annotations cannot express. It does not describe return shape or pagination.

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

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

Two short sentences, no filler. The purpose is front-loaded and the prerequisite follows immediately; each sentence carries distinct information.

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

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

For a zero-parameter, read-only list operation with no output schema, the description covers what is returned and the required setup step. It would be slightly stronger with a note about ordering/pagination or volume, but nothing essential is missing for a correct call.

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

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

The tool takes zero parameters, so there is no parameter syntax for the description to add and the baseline of 4 applies. Nothing misleading is stated about inputs.

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) and resource (all stakeholders) and even enumerates examples of stakeholder types, so the agent knows exactly what data comes back. It does not explicitly differentiate itself from the closely-named sibling get_representatives, which is the only gap.

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

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

Gives a concrete precondition for use: unlock_shareflo must have been called first, naming the sibling tool by name. It does not state when-not to use it or which sibling to pick instead of get_representatives, so it stops short of full routing 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 only declare destructiveHint=false, so the description carries the real burden and does: it discloses that this is proposal-only with no mutation until confirm_action, that unlock_shareflo is a prerequisite, and that Shareflo computes vested amounts from the schedule and surfaces them in the proposal. That is substantive behavior beyond the structured fields.

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

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

Five sentences, each load-bearing: purpose, computed-value behavior, the override constraint, the confirmation gate, and the auth prerequisite. The most important constraint (no effect until confirm_action) is placed prominently.

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 6-param proposal tool with no output schema, the description covers the full operating picture: what is computed, what is deferred, what must precede it, and where the notes requirement applies. An agent can invoke this correctly without further inference.

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 3 is the baseline, but the description adds actionable semantics the schema only partially conveys: the override parameter is a deliberate exception requiring explicit user instruction, and the notes field becomes mandatory in that case. It reinforces rather than duplicates the schema's own parameter docs.

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 ("Proposes stopping vesting on one holding of shares or options") plus the typical trigger (employee leaving). This clearly differentiates it from siblings like amend_vesting or cancel_shares_or_options without needing to open any schema.

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

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

Gives explicit when/when-not guidance for the override path ("Normally you should not provide an overridden_vested_amount; only do so if the user specifically asks"), plus two prerequisites: nothing happens until confirm_action, and unlock_shareflo must run first. It names the exact sibling tools that gate this operation.

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 carry only a title and destructiveHint=false, so the description bears the burden and does so thoroughly: it discloses that the new holding uses tax scheme None, that omitting price means a free transfer, that omitting vesting means no vesting, that partial transfers require vesting to be stopped, and that nothing changes until confirm_action. This is well beyond what the thin annotations 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 long but front-loaded with the core operation and then stacks prerequisites and defaults, with virtually no filler. Each sentence carries distinct information, though the density of constraints makes it slightly heavy to parse in one pass.

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 13-parameter mutation-style tool with no output schema and minimal annotations, the description covers the proposal-only behavior, all key prerequisites, recipient existence, partial-transfer constraints, and default semantics. An agent has everything needed to invoke it correctly without opening other schemas.

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

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

Schema coverage is 100%, so the schema already documents all 13 parameters and the baseline is 3. The description still adds meaningful semantics the schema lacks: omission of price_per_share implies a free transfer and omission of vesting implies no vesting, plus the cliff/vesting_period/vesting_start_date interplay and the take_from conditional.

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 (proposes transferring) plus the resource (shares), the source (one holding), the destination (another stakeholder in the same company), and the resulting state change (recipient gets a new holding, transferor's is reduced). It is clearly distinguishable from sibling tools like create_stakeholder and stop_vesting, which it names by function.

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

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

Explicitly routes the agent to alternatives and states prerequisites: create the recipient with create_stakeholder first, call stop_vesting before a partial transfer, call unlock_shareflo beforehand, and use confirm_action to actually apply. It also rules out a whole class of operation (options can't be transferred), which is exactly the kind of when-not guidance that prevents misfires.

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?

Annotation readOnlyHint=true is consistent with the tool being a read-only rules fetch. The description adds real behavioral context beyond the annotation: mandatory invocation ordering and the failure mode for non-compliance.

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

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

Front-loads the MANDATORY FIRST STEP directive and stays to three sentences. The final sentence restates the mandate already implied earlier, a slight redundancy, but the overall shape is efficient.

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

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

For a zero-parameter, no-output-schema gate tool, the essential information (call first, what it returns, why it matters) is present. It does not describe the form of the returned rules, which is a minor gap given there is nothing to configure.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description is needed to disambiguate arguments, and there are none to mis-specify.

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 action (unlock) and what it yields (the operating rules and constraints governing all other Shareflo tools). Its role as a mandatory prerequisite clearly distinguishes it from the CRUD siblings, though the nature of the returned 'rules' remains abstract.

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

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

Explicitly states when to call it (once at the start of every conversation, before any other Shareflo tool) and the consequence of skipping it (other tools produce incorrect or rejected results). No inference required.

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