company_equity

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal a dual-mode nature — 'inspect' (read) versus 'advance' (mutating lifecycle transition) — and hints at a verification concept via 'verified receipts.' But it never states whether advancing is reversible, what side effects a lifecycle transition triggers, what 'verified receipts' requires, or what the scoped chain is. For a tool that mutates grant state with no annotation safety hints, this is a significant transparency 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 description is a single 13-word sentence with no filler, and the core action is front-loaded ('Inspect or advance option grants'). However, it is compressed to the point of under-specification for a 7-parameter, dual-mode lifecycle tool, and the tail phrase 'scoped chain lifecycle and verified receipts' is dense jargon that trades clarity for brevity.

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 7 parameters with zero schema descriptions, no annotations, and a lifecycle-advancing operation — the description needs to explain the operation modes, lifecycle stages, and bundle_json contract, but explains none of them. The presence of an output schema reduces the need to document return values, yet the input-side ambiguity remains severe enough that the definition is not complete enough for correct invocation.

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

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

Schema description coverage is 0% across 7 parameters, and the description adds essentially no parameter meaning. The two required parameters, project_id and bundle_json, go wholly unexplained — an agent cannot know what bundle_json must contain or how operation/entity_ref/payload_json relate to 'inspect' versus 'advance.' The description's lifecycle jargon is the only hint and it does not map to any specific 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 names a specific resource and action pair — 'inspect or advance option grants' — so an agent can tell this tool deals with equity option grants. However, the phrasing 'through the scoped chain lifecycle and verified receipts' is opaque jargon that obscures the actual mechanism, and nothing distinguishes it from closely related siblings like company_cap_table, company_fundraise, or finance_equity_research_macro_synthesis, all of which sit in the same equity/finance domain.

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

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

There is zero usage guidance. The description does not state when to use this tool versus the many equity-adjacent siblings (e.g., company_cap_table for cap table reads, finance_growth_equity_valuation for valuation), nor does it give any exclusions, prerequisites, or conditions that would select this tool. An agent is left to guess when 'inspect or advance option grants' is the right call.

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