Velarion Company Intelligence

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

Annotations already declare read-only and idempotent behavior, so the description doesn't need to repeat that. It adds useful behavioral context: the tool is based on canonical percentile data and returns pay and TSR percentiles plus an alignment label. The line 'role is CEO-only' is a meaningful scope constraint, though it could be phrased more clearly.

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 compact and front-loaded: purpose first, then return values, then the role constraint. Every sentence earns its place and there is no redundant 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 a rich output schema, full parameter schema coverage, and strong annotations, the description is nearly complete for invoking the tool. The main missing piece is explicit guidance about how this relates to sibling tools such as get_disclosed_peer_group or lookup_company_compensation, so the agent has to infer the intended routing boundaries.

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 ticker, role, agent_token, and fiscal_year. The description adds only the terse 'role is CEO-only' clarification, which is helpful but doesn't substantially extend what the schema already states about parameters.

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

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

The description names a specific verb ('Benchmark'), a specific resource ('executive pay vs. disclosed peers'), and the data source ('Velarion's canonical percentile data'). It lists concrete outputs, which makes the tool's function unmistakable and distinguishes it from siblings like get_disclosed_peer_group or get_company_compensation.

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 the usage context: call this when the agent needs a peer-relative pay benchmark with percentile outputs. It does not explicitly name alternative tools or state when not to use it, but the purpose is specific enough that an agent can route to it correctly.

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 adds meaningful behavioral context beyond the annotations: it clarifies that the returned table is based on disclosed data, that the summary only describes patterns in the returned data, and that out-of-coverage tickers are excluded but listed separately. These caveats help prevent an agent from over-generalizing results or silently dropping tickers, which is strong transparency for a read-only, idempotent tool.

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

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

The description is four short sentences with no filler. The opening sentence states the core purpose, the second clarifies the output nature, the third prevents over-interpretation of the summary, and the fourth discloses coverage limits and handling. 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?

Given that an output schema exists, annotations cover the safety profile, and the description explains the tool's multi-company scope, ranking output, coverage behavior, and summary limitation, the definition provides everything an agent needs to select and invoke 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 baseline is 3. The description adds little parameter-specific meaning beyond repeating the 'max 20 tickers' constraint already present in the schema, so it does not exceed the 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?

The description clearly identifies the action ('Compare multiple companies') and the resource domain ('pay, performance, and governance metrics'), and specifies the output as a ranked table. However, it does not explicitly differentiate this tool from closely related siblings such as benchmark_executive_pay, which may also involve comparison, so it falls short of full sibling-level distinction.

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 makes the primary use case explicit: comparing multiple companies on relevant metrics, with a hard limit of 20 tickers and a stated behavior for out-of-coverage tickers. It does not explicitly mention when not to use this tool or name a preferred alternative, so it earns a 4 rather than a 5.

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/idempotent/non-destructive annotations, the description discloses a per-agent daily free-tier cap with the exact error code (free_tier_cap_reached) and reset timing (00:00 UTC), plus three named structured-error conditions returned rather than raised. It also explains that there is no purchase path, so agents won't hallucinate an upsell step. That is precisely the behavioral 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?

The purpose and coverage requirement are front-loaded, which is good, but the middle paragraph is internal product-death provenance — a verbatim chat quote, an order-document path, and a discussion of a killed paid product — that does not help an agent invoke the tool. The one operationally useful fact there (the free tool still exists, there is nothing to buy) could be a single clause.

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 explanation, and the description closes the remaining gaps: preconditions (coverage universe, current-period data), rate limiting, and all failure modes with error codes. The only soft spot is that it never says how an agent can test whether a ticker is in coverage before spending a 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?

Schema description coverage is 100% — ticker, optional fiscal year with default, and agent_token with header fallback are all documented inline. The description adds nothing about parameter format or interactions, 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?

The first sentence gives a specific verb+resource ("Generate a Governance Alpha Card") and the second enumerates its contents (pay alignment, governance scorecard, SoP risk band, peer quality, risks/strengths), so an agent knows this is a composite per-company report generator. It does not explicitly distinguish itself from near-neighbors such as predict_say_on_pay_risk or get_company_compensation, which keeps it below 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?

"Requires the company to be in Velarion's coverage universe with current-period data" plus the error list implies when the tool is usable, and the free-sample framing hints at a lightweight alternative to the paid product. However, there is no explicit instruction on when an agent should reach for this card instead of the sibling lookup tools, or how to verify coverage before calling (e.g. via search_companies).

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, idempotentHint, and non-destructive behavior. The description adds useful context beyond those annotations: it is limited to the free plan and returns only the most recent disclosed ratio, which helps the agent understand data recency and access constraints.

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 filler. It front-loads the access constraint and clearly states the exact data item returned, making every word valuable.

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-value details are covered elsewhere. The description sufficiently covers what data is returned and the access tier, though it could briefly clarify that 'CEO pay ratio' refers to the CEO-to-median-employee pay ratio for agents unfamiliar with the term.

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 ticker and agent_token parameters are already fully documented in the schema. The description adds no additional parameter-level meaning, which is acceptable given the complete schema 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 clearly states the resource ('CEO pay ratio') and the specific verb implied by the tool name ('get'), plus the exact scope: the most recent disclosed ratio. This is specific enough to distinguish it from sibling compensation tools, which target different metrics.

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 'Free plan:' prefix suggests an access-tier context, and the resource is self-explanatory, but the description does not explicitly say when to prefer this over alternatives like get_company_compensation or get_say_on_pay_history. Usage is implied rather than directly guided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the data-coverage window (FY2022 forward), the per-figure citation behavior, and the explicit absence of benchmark/percentile/narrative content. This is useful behavioral context beyond the annotations and schema.

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 no filler; the free-plan limitation, exact return contents, and feature exclusions are all front-loaded. Every sentence adds information about scope or behavior. This is an appropriately sized description for a read-only retrieval 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?

With a full input schema (100% coverage), an output schema, and safety annotations, the description covers the essential use case and limitations. It does not explicitly differentiate itself from lookup_company_compensation, but the 'free plan' vs 'paid product' contrast plus the specific SCT components make the intent clear. A minor gap is the lack of a named sibling for paid capabilities, but the description is broadly complete.

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 ticker, agent_token, and fiscal_year. The description mentions fiscal-year scope but does not add meaning beyond the schema's 'optional fiscal year to read' description. Baseline 3 applies because the schema carries the parameter documentation 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 names a specific verb ('returns') and a precise resource: Summary Compensation Table components for named executive officers from fiscal year 2022 forward. It explicitly scopes out benchmark context, percentiles, and narrative analysis, which separates it from sibling tools like benchmark_executive_pay and generate_governance_alpha_card. The 'free plan' label clarifies which product tier this belongs to.

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 the tool is the free-plan version and that benchmark context, percentiles, and narrative analysis are only in the paid product, signaling when not to use this tool. The exclusion is explicit enough to route an agent away from benchmark or analysis tasks, though it does not name a specific sibling alternative. It does not cover when to choose get_company_compensation over lookup_company_compensation or get_director_compensation, but the core usage context is 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 already mark the tool as read-only, idempotent, and non-destructive, so the description does not need to restate those. It adds useful behavioral context: the free-plan scope and the fact that unpaid directors are listed separately from the paid table. 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 short sentences, with the free-plan qualifier front-loaded. The second sentence earns its place by revealing a data-organization quirk that affects how results should be interpreted. 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 an output schema present, safety annotations covering behavior, and full parameter documentation, the description is nearly complete for a correct call. The only meaningful gap is routing guidance relative to sibling compensation tools, which keeps it from a perfect score.

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 ticker, agent_token, and fiscal_year. The description adds no parameter-specific meaning, which is acceptable given the schema's clarity. 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 clearly identifies the resource: non-employee director compensation and the board fee schedule, and the title adds 'free'. It distinguishes from broader siblings like get_company_compensation by scoping to non-employee directors. However, it lacks an explicit verb like 'get' or 'retrieve', relying on the tool name for the action.

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 'Free plan' prefix gives context about access tier, and the unpaid-directors note clarifies a scoping edge. But it never explicitly tells the agent when to choose this tool over get_company_compensation or lookup_company_compensation, nor states exclusions. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds mild context by noting the data reflects the most recent fiscal year on file, but it does not disclose behavior beyond that, such as response shape or data-source caveats.

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 that front-loads the 'Free plan' context and immediately defines the returned data. It is efficient and contains no filler, though it is a noun phrase rather than a complete imperative sentence.

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?

This is a simple read-only lookup with a high-coverage schema and an output schema, so the description conveys enough to understand the tool's core purpose. It could be more complete by addressing when the free-plan data might differ from paid alternatives or by naming sibling tools, but nothing critical is missing for basic 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%, so the ticker and agent_token parameters are already well documented. The description does not add any parameter-level meaning beyond what the schema 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?

The description identifies a specific resource: the company's disclosed compensation peer group for the most recent fiscal year. It is clear that this tool returns peer-group data for a single company, but it does not explicitly differentiate itself from siblings like compare_companies or get_company_compensation.

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

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

No explicit guidance is given about when to use this tool instead of alternatives. The 'Free plan' prefix hints at plan constraints, but it does not tell the agent when this endpoint is preferable over sibling compensation tools.

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, idempotentHint=true, and destructiveHint=false. The description adds non-obvious behavioral context: support percentages are calculated by Velarion from disclosed vote counts and marked as such in the citation. This is valuable beyond the structured annotations, with no contradiction.

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 short and front-loaded, and the methodology note earns its place. The first sentence largely restates the title, creating minor redundancy, but overall there is no wasted 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?

Given the simple read-only nature, full parameter documentation, and presence of an output schema, the description covers the key caveat about calculated percentages. It is complete enough for correct invocation, though usage guidance is absent.

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

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

Input schema coverage is 100%, with both ticker and agent_token already described. The description does not add parameter-level detail, so baseline 3 is appropriate since the schema carries the full 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 clearly identifies the resource as say-on-pay vote history with a specific verb ('get' implied). It is distinguishable from siblings like predict_say_on_pay_risk by the vote-history scope, though it does not explicitly contrast itself with any sibling.

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 about when to use this tool versus alternatives such as get_company_compensation, get_ceo_pay_ratio, or predict_say_on_pay_risk. The 'Free plan' label hints at access conditions but does not explain prerequisites or exclusions.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation. Beyond that, the description adds useful behavioral context: reports are grouped into `sellable` versus `buy_on_web`, non-sellable items are tagged with status, and products without settled prices are returned as status rather than billable amounts.

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 the core action and then expands into catalog behavior. It is somewhat long but every major sentence contributes useful information about grouping, conditional inclusion, and edge-case pricing.

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 presence of an output schema, the description does not need to document every return field. It still covers the major output categories, the conditional parameter, and the no-settled-price edge case, making the tool's behavior 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 coverage is 100%, so the parameters are already documented. The description still adds meaning to `include_non_sellable` by explaining that it exposes the full catalog range and that non-sale products carry status tags; `agent_token` is only weakly elaborated 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 gives a specific verb and resource: listing the Velarion product catalog. It immediately distinguishes the object being returned and explains the key catalog groupings (`sellable`, `buy_on_web`), so an agent can tell what this tool does 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?

The description clearly states when to set `include_non_sellable=true`, namely to include products not currently on sale and see the full range. It does not name an alternative tool, but the sibling tools are unrelated governance/compensation tools, so there is no meaningful sibling choice to route between.

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 readOnly, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: figures come from the company's own disclosure with citations, and out-of-coverage tickers produce a structured not_in_coverage error. This is useful operational context and does not contradict 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 tightly structured: purpose first, return contents second, error behavior third. Every sentence earns its place, with no redundant or vague 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?

Given the rich input schema, annotations, and output schema, the description covers the essential invocation concerns: what is returned, the default fiscal-year behavior, and the error case. The main missing piece is explicit routing among the compensation-related sibling tools, which is a selection concern rather than an invocation blocker.

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 reiterates the fiscal-year default ('latest available if omitted') but adds no parameter-specific context beyond what the schema already documents. No additional semantics are needed, but none are contributed either.

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 and resource: 'Look up executive compensation for a company in Velarion's coverage universe,' and it spells out the returns (CEO/NEO total comp, pay mix, canonical metrics). It does not explicitly contrast with siblings like get_company_compensation or get_ceo_pay_ratio, so it stops short of full sibling differentiation.

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 use for looking up executive compensation within Velarion's coverage and gives an important boundary condition: out-of-coverage tickers return a structured error. However, it gives no explicit guidance on when to choose this tool over the compensation-related siblings or when not to use 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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds non-obvious behavioral detail: it is deterministic and produces four named output components derived from vote/compensation data. This communicates what the agent will receive beyond what the annotations state.

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 no filler; the action and outputs are front-loaded. Every clause adds information, including the data sources and the deterministic nature.

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 all parameters documented, the description does not need to restate return structure. It is complete enough to call for a risk prediction, though it could be strengthened by adding selection guidance versus sibling tools.

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 no parameter-specific detail beyond the schema. It does not mention ticker, agent_token, or fiscal_year, but the schema already documents their types and defaults.

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 leads with a specific verb and resource ('Predict Say-on-Pay risk for a company') and lists concrete outputs, so an agent can tell it is a risk-scoring operation rather than a raw lookup like get_say_on_pay_history. The reference to 'deterministic risk compilers' further differentiates it from sibling tools. This makes the 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?

No explicit when-to-use or when-not-to-use guidance appears; the description never names alternatives such as get_say_on_pay_history or benchmark_executive_pay. The context implies this tool is for generated risk predictions ('computed from disclosed vote results'), but exclusions and selection criteria are left to the agent.

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, idempotentHint, and destructiveHint, so the basic safety profile is covered. The description adds useful behavioral constraints: 'Requires a query of at least two characters' and 'returns at most 10 results,' which go beyond annotations. It does not disclose rate limits or coverage details, but the added constraints earn a 4.

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 no wasted words. The first sentence states the core function and scope; the second provides the key constraints. All information is front-loaded, making it easy for an agent to parse quickly.

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 this is a simple search tool with an output schema, the description covers the essential constraints (minimum query, result limit) and the scope ('covered universe'). The optional token authentication is documented in the schema. Nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description essentially repeats what the query schema already states (company name or ticker, at least 2 characters). The agent_token parameter is not mentioned in the description, but the schema already fully documents it. No additional parameter meaning is added 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 a specific verb and resource: 'search Velarion's covered universe by company name or ticker.' It distinguishes itself by emphasizing the free-plan limitation and basic search scope. However, it does not explicitly contrast with any sibling tools, so it falls just short of a 5.

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

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

The description implies when to use it: when you need a free, basic company search by name or ticker. It provides operational constraints (minimum query length, maximum result count) but does not mention alternatives or explicitly state when not to use it. This is clear context but no exclusions or routing.

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