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?

Annotations only supply destructiveHint=true, and the description adds real context beyond that: it is a commit/mutation step gated on human confirmation, it can fail on insufficient permission, and it depends on a prior unlock call. It does not say whether the commit is reversible or what a success response looks like, but the safety-relevant behavior is well covered and consistent with destructiveHint.

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 short sentences that each carry distinct load: purpose, confirmation precondition, permission failure mode, and unlock prerequisite. The purpose is front-loaded 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 single-parameter destructive tool with no output schema, the definition covers purpose, precondition, failure mode, and dependency. The only real gap is that it never hints at the return/result of a successful commit, which an agent may want when chaining calls.

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 the schema already explains that proposal_uid comes from the tool call that created the proposal (e.g. create_holding). The description adds no format or sourcing detail beyond that, so the baseline 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?

States a specific verb and resource ('Commits one existing action proposal to the cap table'), which separates it from the create_* siblings that generate proposals in the first place. The word 'existing' plus the required prior unlock makes the two-step flow 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?

Explicitly states the triggering condition ('only after the user has actively confirmed the exact proposal shown to them') and the prerequisite ('Requires unlock_shareflo to have been called first'), naming the sibling tool by name. There is nothing left to infer about when to call 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?

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 already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful context beyond the annotations: the sequencing dependency on unlock_shareflo and the fact that results carry holding status. No pagination or volume behavior is mentioned, keeping it out of the top band.

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 waste, with the primary behavior and its two modes front-loaded ahead of the prerequisite. 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?

No output schema exists, so the description carries some return-value burden; it mentions holding status but not the broader shape of a holding record. Prerequisite, scope, and parameter behavior are all covered, so only return-format detail 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% so the baseline is 3, and the description goes further by explaining the semantic effect of omitting the optional stakeholder parameter (returns every stakeholder's holdings). That is real added meaning, though it adds no format or matching-syntax 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?

States a specific verb (returns) and resource (holdings) with two clearly delineated modes: filtered by stakeholder or all stakeholders. This distinguishes it from siblings like get_stakeholders and get_instruments at a glance.

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 condition for each mode (specify stakeholder to filter, omit to get all) and gives a hard prerequisite: unlock_shareflo must have been called first. It stops short of naming alternative tools, but the usage condition 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 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?

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.