company-intelligence

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

With no annotations, the description carries the full burden. It discloses the return fields, notes no LLM involvement, and mentions the CEO-only limitation. It does not address idempotency, security, or rate limits, but covers core behavioral aspects adequately.

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

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

The description is extremely concise—two sentences plus a short note—with no wasted words. It is front-loaded with the primary purpose and details are separated clearly.

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

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

Given the tool has 4 parameters (0% coverage) and no annotations, the description is moderately complete. It lists return values and a key limitation (CEO-only) but lacks parameter descriptions, usage examples, or error handling. An output schema exists, which reduces some burden.

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

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

Schema description coverage is 0%, so the description must compensate. It only adds context for the role parameter (CEO-only), but provides no explanation for ticker, fiscal_year, or agent_token. This is insufficient for the agent to understand parameter usage.

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

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

The description clearly states the tool benchmarks executive pay vs disclosed peers using Velarion's canonical percentile data, listing specific return metrics. It distinguishes itself from sibling tools like lookup_company_compensation and predict_say_on_pay_risk by focusing on percentile-based benchmarking.

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 notes that role is currently CEO-only, providing a key constraint, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Usage context is implied but not fully 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?

With no annotations provided, the description discloses key behaviors: data source (Velarion's canonical_metrics), no LLM narrative invention, data-based summary only, max limit, and exclusion handling. This is sufficient for a non-destructive 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 providing unique value: purpose, data source, behavior constraints, and limitations. No wasted words, front-loaded with the core function.

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

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

An output schema exists but is not shown; the description compensates by describing the output (ranked table, data-based summary). It covers key limitations but leaves agent_token and fiscal_year unexplained, which is a minor gap given the 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?

Schema coverage is 0%, so the description should compensate. It only adds the max 20 constraint for tickers but does not explain agent_token or fiscal_year. The meaning of tickers as company tickers is implicit but not explicitly stated.

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

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

The description clearly states the tool compares multiple companies on pay, performance, and governance metrics, which distinguishes it from siblings like benchmark_executive_pay (single metric) and lookup_company_compensation (single company). The verb 'compare' and resource 'companies' are specific.

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 (comparing companies on multiple metrics) and gives constraints (max 20 tickers, out-of-coverage excluded). However, it does not explicitly say when not to use it or compare against alternatives like benchmark_executive_pay.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It describes the ownership gate (security enforcement) and settlement gate (fail-closed behavior), including historical context. It also explains that on verified settlement it calls compile_and_deliver via the same code path as other entry points. This provides good insight into internal behavior, though it omits details like idempotency or side effects.

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 moderately concise—it starts with a clear one-sentence summary, then expands into necessary detail about the two gates. Some sections (e.g., the parenthetical about the security bug) are verbose but informative. It is well-structured with clear separation of concerns, though it could be trimmed without losing value.

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

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

Given the tool's critical function (fulfillment and artifact delivery) and the presence of an output schema, the description covers the core behavior and constraints. However, it does not explain how to verify a quote is paid, possible error responses beyond settlement_unverified, or what the artifact consists of. The lack of parameter descriptions and postconditions makes it somewhat incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It only implicitly mentions 'quote_id' through the ownership gate, and the 'agent_token' parameter is completely unexplained (default '' but no semantics). The description does not add meaningful parameter context beyond what the schema provides (names and types).

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 verb 'fulfill' and the resource 'paid custom quote', with the action 'compiling and delivering its artifact'. This distinguishes it from siblings like place_order (placing an order) and price_product (pricing). The purpose is specific and unambiguous.

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

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

The description provides explicit conditions for use: the quote must be owned by the agent account and settlement must be verified. It states that without verified settlement, the tool returns 'settlement_unverified' and does not call compile_and_deliver. However, it does not compare to alternative tools or explicitly state 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?

With no annotations provided, the description fully discloses behavior: it is deterministic, calls internal functions (generate_alpha_card, evaluate_deliverability), explains the free-tier cap mechanism, and states that errors are returned (not raised) for specific conditions. This exceeds the burden for a tool without 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 front-loaded with purpose but becomes verbose with internal implementation details (e.g., 'calls generate_alpha_card ...') and a confusing sentence about 'PRICE_INTEGRITY blocker.' It could be more succinct while retaining essential 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?

Given the tool's complexity (3 parameters, multiple error states, an output schema), the description covers most aspects: purpose, prerequisites, error cases, and free-tier cap. It lacks parameter explanations, but the presence of an output schema reduces the need to describe return values.

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

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

Schema description coverage is 0%, and the description does not explain the two optional parameters (year, agent_token). It only implicitly mentions 'ticker' is required. The agent lacks guidance on what 'year' means (e.g., fiscal year?) or the role of 'agent_token', making parameter usage unclear.

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

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

The description clearly states the tool's purpose: 'Generate a Governance Alpha Card for a company.' It details the card's components (pay alignment, governance scorecard, etc.) and specifies it requires the company to be in Velarion's coverage universe. This differentiates it from sibling tools like benchmark_executive_pay or compare_companies, which serve different functions.

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

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

The description provides explicit conditions for use: the company must be in coverage with current-period data. It also mentions structured errors for not_in_coverage and not_deliverable, guiding the agent on when the tool will fail. However, it does not explicitly contrast with alternatives (e.g., 'use this instead of predict_say_on_pay_risk').

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 no annotations, the description fully bears the burden. It discloses that unverified prices are never fabricated and items are de-prioritized not hidden. Lacks details on authentication or rate limits, but overall transparent for a listing 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?

Description is approximately 120 words, efficiently packed with useful information. Front-loaded with purpose, uses bullet-like structure for return fields, and no superfluous sentences.

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 there is an output schema, the description does not need to detail return values. It covers default behavior, parameter effects, and edge cases (non-sellable items) comprehensively. No obvious gaps.

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

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

Schema description coverage is 0%, so description must compensate. It explains include_non_sellable thoroughly (effect, return types) but does not document agent_token. One of two parameters is well-covered.

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

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

The description clearly states the tool lists the Velarion catalog, with specific verb 'List' and resource 'catalog'/'products'. It distinguishes from siblings like place_order or fulfill_paid_order, which are not listing tools.

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

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

The description explains default behavior (returns APPROVED_SELLABLE) and how to extend with include_non_sellable parameter. It does not explicitly state when NOT to use, but given no sibling listing tools, the 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?

Without annotations, the description carries the burden. It discloses the data source (Supabase, no invented values) and error type. It implies a read-only operation via 'look up'. This adds useful context beyond the schema, though more details on authentication or rate limits would help.

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

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

The description is three sentences, no wasted words, and front-loads the purpose. Every sentence adds value (purpose, return content, data provenance, error handling).

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 an output schema exists (not shown), the description need not detail return fields, but still summarizes them well. It mentions error cases and data source. Minor omission: does not specify that only one fiscal year is returned or that the tool may not support multiple years. Overall sufficiently complete for a lookup tool.

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

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

Schema description coverage is 0%, so the description must add meaning. It explains that fiscal_year defaults to the latest available if omitted. However, it does not describe the ticker (beyond implying it's a company identifier) or the agent_token parameter, leaving some semantics to be inferred.

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

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

The description clearly states the tool looks up executive compensation for a company, specifying the coverage universe and return values (CEO/NEO total compensation, pay mix, canonical metrics). It does not explicitly differentiate from siblings like benchmark_executive_pay, but the verb 'look up' and scope are specific enough.

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

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

The description provides context on when to use (for companies in coverage) and error behavior for out-of-coverage tickers, but does not give explicit guidance on when not to use or compare with siblings such as benchmark_executive_pay.

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?

No annotations provided, so description bears full burden. Discloses mutation (creates quote, not final charge), scope of action (owned by agent account), and specific rejection behavior (too_many_tickers). Lacks details on potential errors or idempotency.

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 one-sentence summary, then structured sections for context, requirements, and cohort details. Slightly lengthy but each sentence adds value. No wasted words.

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 output schema exists (return format not needed), description covers key aspects: buy path positioning, authentication, cohort constraints, and rejection behavior. Could mention error states or additional parameters.

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 0% per context signals. Description adds meaning: explains tickers cap at 15, subject_ticker default, and cohort product rules. However, agent_token and scope_params are not explained.

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?

Clearly states 'Place an order for a priced product — creates a quote you can pay and then fulfill.' Differentiates from sibling tools price_product and fulfill_paid_order by positioning itself in the buy path.

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 use: after price_product, before fulfill_paid_order. Lists prerequisites (mcp:buy scope, Velarion commerce account) and notes rejection behavior for excessive tickers.

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 no annotations provided, the description carries the burden of disclosing behavioral traits. It mentions the tool is fully deterministic (no LLM), but does not confirm read-only status, authorization needs, or potential side effects. The description lacks transparency expected for a prediction 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 concise, with three short sentences front-loading purpose and key features. The compiler references add specificity without excessive length.

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 three parameters, no coverage, and no annotations, the description is too sparse. It does not explain input requirements (e.g., ticker format), output structure despite an output schema existing, or edge cases. The agent lacks sufficient context to use the tool confidently.

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%, yet the description fails to explain any of the three parameters (ticker, agent_token, fiscal_year). It only references internal data sources without clarifying parameter meaning or constraints.

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

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

The description clearly states the tool predicts Say-on-Pay risk for a company using deterministic compilers. It mentions the return type (trend phrase, peer cohort distribution note, etc.) and distinguishes itself from siblings like benchmark_executive_pay by emphasizing determinism and specific compilers. However, it could be more explicit about the exact output structure.

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

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

No guidance is provided on when to use this tool versus alternatives such as benchmark_executive_pay or compare_companies. The description implies a use case for deterministic risk assessment but does not specify 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?

With no annotations, the description fully discloses behaviors: price floor deletion, profit-aware pricer, no fabricated returns, and detailed status outcomes. This is comprehensive.

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 verbose with detailed status explanations. While front-loaded with purpose, it could be more concise by deferring details to the output schema or separate sections.

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?

Has output schema and explains returns for each status, but fails to document all parameters. Given 5 parameters, the description is incomplete without explaining ticker, buyer_type, etc.

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 0%, so description must compensate. It explains product_type (SKU ID or family) but does not describe ticker, buyer_type, agent_token, or scope_params, leaving gaps.

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

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

The description clearly states the tool prices Velarion products, handles all SKUs, and explains outputs for different statuses. It is distinct from siblings like list_skus (listing) and fulfill_paid_order (fulfillment).

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 on when to use this tool versus alternatives. The description does not compare to sibling tools or specify context where this tool is preferred.

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