Deterministic profitability and market-value ratios — margins, ROA/ROE/ROCE/ROIC, EPS, P/E, P/B, dividend yield, payout.
Calculate dividend yield: annual dividends per share divided by share price — the cash return a shareholder receives from dividends. Formula: Dividend Yield = Annual Dividends Per Share / Share Price. WHEN TO USE: Use to compare income return against bond yields or peer dividend policies; a yield far above peers can signal a depressed price or unsustainable payout. WHEN NOT TO USE: Do NOT annualise a one-off special dividend as if it were regular income. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { dividend_yield: decimal (e.g. 0.035 = 3.5%), dividend_yield_pct: number (e.g. 3.5), inputs }. PARAMETERS: annual_dividends_per_share (required): Annual dividends per share, e.g. 1.58. Must be >= 0. share_price (required): Current share price, e.g. 45.00. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| share_price | Yes | Current share price, e.g. 45.00. Must be > 0. | |
| annual_dividends_per_share | Yes | Annual dividends per share, e.g. 1.58. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states the calculation is pure, deterministic, side-effect free, idempotent, and non-destructive, and discloses division-by-zero/non-finite error behavior. This adds real behavioral context beyond the annotations, which already declare readOnlyHint, idempotentHint, and destructiveHint. One small gap: it does not describe the shape of the error object returned, but the core behavioral contract is clearly stated.
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 well-structured with clear sections: definition, formula, when-to-use, when-not-to-use, behavior, returns, and parameters. Every sentence carries information an agent needs, and the key formula is front-loaded so an agent can immediately classify the tool and its inputs.
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 two-parameter pure calculation with full schema coverage and clear annotations, the description covers every behavioral aspect: the formula, input constraints, division-by-zero handling, return format with examples, and usage boundaries. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description reinforces each parameter's meaning and constraints (must be >= 0, must be > 0) with concrete examples. It adds the formula context connecting the two parameters and clarifies that the result represents cash return. This is a solid baseline-plus contribution, though the examples mostly echo 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 opens with a precise verb-resource pairing: 'Calculate dividend yield' followed by the exact formula. It distinguishes itself from the financial-ratio sibling tools by defining its specific inputs (annual dividends per share, share price) and output (dividend yield as a decimal and percentage).
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?
Explicit WHEN TO USE and WHEN NOT TO USE sections. The when-to-use directs agents toward comparing income returns against bond yields or peer dividend policies, and the when-not-to-use warns against annualizing a one-off special dividend — a genuinely useful decision rule that no formulaitc sibling would share.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate earnings per share (EPS): net income divided by weighted average shares outstanding — profit attributable to each share. Formula: EPS = Net Income / Weighted Average Shares Outstanding. WHEN TO USE: Use as the denominator for P/E and payout ratios and to track per-share profitability over time. WHEN NOT TO USE: Do NOT use basic share count when convertible securities exist — use diluted shares for a conservative EPS. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { eps: number (currency per share, e.g. 1.25), inputs }. PARAMETERS: net_income (required): Net income attributable to common shareholders, e.g. 1250000. May be negative. weighted_avg_shares_outstanding (required): Weighted average shares outstanding during the period, e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| net_income | Yes | Net income attributable to common shareholders, e.g. 1250000. May be negative. | |
| weighted_avg_shares_outstanding | Yes | Weighted average shares outstanding during the period, e.g. 1000000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description goes beyond them: it states no side effects, no network or storage access, deterministic identical-input-identical-output behavior, and — most valuably — the division-by-zero/non-finite error contract ('returns an explicit error instead of a number'). This error behavior is not recoverable from annotations and is critical for an agent to anticipate failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized with clear section labels (WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and front-loads the definition and formula. Each section earns its place; the only minor inefficiency is the PARAMETERS block redundantly repeating schema content already shown in the input schema.
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 2-parameter, no-output-schema, no-nested-object tool, everything an agent needs is present: the calculation formula, input constraints, edge-case error behavior, the JSON return shape ({ eps: number, inputs }), and usage context. Since no output schema exists, the description correctly fills the return-format gap itself.
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% — both parameters are fully documented with meaning, examples, and constraints (negative allowed for net_income; exclusiveMinimum 0 for weighted shares). The description's PARAMETERS section essentially duplicates the schema verbatim, adding no new semantic information, so the high-coverage baseline of 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 ('Calculate earnings per share'), provides the defining formula (EPS = Net Income / Weighted Average Shares Outstanding), and adds a plain-language interpretation ('profit attributable to each share'). The formula semantics unambiguously distinguish it from all 11 sibling ratio calculators (P/E, margins, ROE, etc.).
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?
Contains explicit WHEN TO USE and WHEN NOT TO USE sections. It tells the agent this tool feeds P/E and payout ratios and supports per-share profitability tracking, and it gives a concrete exclusion: do not use basic share count when convertible securities exist — use diluted shares. This is explicit, actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate gross margin: gross profit divided by net sales — the share of revenue retained after the direct cost of goods sold. Formula: Gross Margin = Gross Profit / Net Sales. WHEN TO USE: Use to assess product-level economics and pricing power before operating expenses are considered. WHEN NOT TO USE: Do NOT use gross margin to compare companies with different cost classification practices (COGS boundary varies). BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { gross_margin: decimal (e.g. 0.40 = 40%), gross_margin_pct: number (e.g. 40.0), inputs }. PARAMETERS: gross_profit (required): Gross profit = net sales - COGS, e.g. 400000. Must be >= 0. net_sales (required): Net sales / revenue, e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| net_sales | Yes | Net sales / revenue, e.g. 1000000. Must be > 0. | |
| gross_profit | Yes | Gross profit = net sales - COGS, e.g. 400000. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The BEHAVIOUR section goes well beyond the annotations, detailing that the calculation is pure, deterministic, has no side effects, and returns an explicit error for division by zero or non-finite inputs. This adds meaningful context that annotations alone do not convey, and there is 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 well-organized with clear sections (formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and is mostly information-dense. There is slight redundancy between the opening explanation and the explicit formula, preventing a perfect score.
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 simple two-parameter calculation with no output schema, the description covers every aspect needed to invoke it correctly: formula, parameter semantics, return value shape, error behavior, and usage context. Nothing essential 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's PARAMETERS section essentially restates the schema's descriptions and constraints without adding new meaning or clarifying relationships beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Calculate gross margin') and immediately defines the formula, making the tool's purpose unambiguous. The precise formula and explanation of 'share of revenue retained after the direct cost of goods sold' clearly differentiates it from sibling ratio calculators such as net margin or operating margin.
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?
WHEN TO USE and WHEN NOT TO USE are explicitly provided with concrete context: assessing product-level economics and a warning about comparing companies with different COGS classification practices. However, it does not explicitly name an alternative sibling tool, so it stops short of the full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate net margin: net income divided by net sales — the share of every revenue pound/dollar that reaches the bottom line. Formula: Net Margin = Net Income / Net Sales. WHEN TO USE: Use for the all-in profitability picture after operating costs, interest, tax and other items. WHEN NOT TO USE: Do NOT use alone — net margin is affected by capital structure and tax; compare alongside gross and operating margins. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { net_margin: decimal (e.g. 0.12 = 12%), net_margin_pct: number (e.g. 12.0), inputs }. PARAMETERS: net_income (required): Net income after tax, e.g. 120000. May be negative. net_sales (required): Net sales / revenue, e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| net_sales | Yes | Net sales / revenue, e.g. 1000000. Must be > 0. | |
| net_income | Yes | Net income after tax, e.g. 120000. May be negative. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint), the description adds concrete behavioral details: pure deterministic calculation, no side effects, no network/storage access, identical inputs give identical outputs, and division-by-zero/non-finite inputs return an explicit error. This is valuable operational context an agent cannot infer from annotations alone.
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 well structured with clear sections (formula, when to use, when not to use, behavior, returns, parameters). Despite its length, every sentence carries operational value, and the core purpose is front-loaded.
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 simple pure-calculator tool with no output schema, the description fully covers inputs, outputs, error behavior, and usage boundaries. An agent has all necessary information to select and invoke this 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 coverage is 100%, and the description closely mirrors the schema for net_income and net_sales, adding no meaning beyond what the schema already provides. The formula context is helpful but does not materially change parameter understanding, so the 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 states a specific verb ('Calculate'), the exact resource ('net margin'), and the formula (Net Income / Net Sales), defining the all-in profitability picture. This distinguishes it clearly from sibling tools like calculate_gross_margin and calculate_operating_margin even without comparing schemas.
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 includes explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections. It directs agents to compare alongside gross and operating margins, clearly preventing misuse in isolation and distinguishing this from related ratio tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate operating margin: operating income divided by net sales — profitability from core operations before financing and tax. Formula: Operating Margin = Operating Income / Net Sales. WHEN TO USE: Use to compare core business profitability across peers and over time, independent of capital structure. WHEN NOT TO USE: Do NOT use when one-off items distort operating income — consider normalised EBIT instead. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { operating_margin: decimal (e.g. 0.18 = 18%), operating_margin_pct: number (e.g. 18.0), inputs }. PARAMETERS: operating_income (required): Operating income / EBIT, e.g. 180000. May be negative. net_sales (required): Net sales / revenue, e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| net_sales | Yes | Net sales / revenue, e.g. 1000000. Must be > 0. | |
| operating_income | Yes | Operating income / EBIT, e.g. 180000. May be negative. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description reinforces this by stating 'pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive.' It also adds useful edge-case behavior: division by zero or non-finite inputs returns an explicit error.
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 well-structured with labeled sections (WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and front-loads the core definition and formula. Every sentence adds operational or selection value, with 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?
The description covers purpose, usage boundaries, behavioral guarantees, error handling, return shape, and parameter constraints. It is complete enough for an agent to call the tool correctly even without an output schema, and the annotations supply the remaining safety profile.
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 applies. The description repeats the parameter meanings and constraints (operating income may be negative, net_sales must be > 0), but adds little beyond the schema, aside from embedding them in the formula context. This meets the minimum viable bar but does not substantially augment the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Calculate operating margin: operating income divided by net sales,' and clarifies the financial meaning ('profitability from core operations before financing and tax'). It includes the exact formula, distinguishing it from sibling margin/ratio calculators.
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 WHEN TO USE guidance and an explicit WHEN NOT TO USE exclusion, naming 'normalised EBIT' as the alternative when one-off items distort operating income. This is exactly the kind of routing information an agent needs to choose correctly among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the payout ratio: dividends per share divided by earnings per share — the share of profits distributed as dividends. Formula: Payout Ratio = Dividends Per Share / EPS. WHEN TO USE: Use to judge dividend sustainability: payout above 100% means dividends exceed earnings (funded by debt or reserves). WHEN NOT TO USE: Do NOT use when EPS is negative (ratio is meaningless), and note young growth companies legitimately pay little or nothing. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { payout_ratio: decimal (e.g. 0.55 = 55%), payout_ratio_pct: number (e.g. 55.0), inputs }. PARAMETERS: dividends_per_share (required): Dividends per share in the period, e.g. 1.34. Must be >= 0. earnings_per_share (required): Earnings per share, e.g. 2.43. Must be > 0 for a meaningful ratio.
| Name | Required | Description | Default |
|---|---|---|---|
| earnings_per_share | Yes | Earnings per share, e.g. 2.43. Must be > 0 for a meaningful ratio. | |
| dividends_per_share | Yes | Dividends per share in the period, e.g. 1.34. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states the tool is a pure deterministic calculation with no side effects, no network or storage access, and is idempotent and non-destructive. It also discloses error behavior for division by zero or non-finite inputs, adding value beyond the annotations alone.
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 organized into clear labeled sections: formula, when to use, when not to use, behaviour, returns, and parameters. Every sentence adds useful information, and no filler or redundant phrasing is present.
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 no output schema, the description thoroughly explains the return JSON structure with example values. It covers safety, error behavior, input constraints, usage context, and exclusions, making the tool fully self-contained for an agent to invoke 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 coverage is 100%, so the schema already fully documents both parameters. The description restates the parameter constraints but does not add significant new meaning beyond what the structured schema provides, so the baseline 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?
The description uses a specific verb ('Calculate') with a clearly defined resource ('payout ratio') and gives the exact formula (Dividends Per Share / EPS). It is immediately distinguishable from the sibling ratio/margin calculators because it names its unique inputs and interpretation.
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?
Explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections tell the agent to judge dividend sustainability and warn against using the tool when EPS is negative or for young growth companies. This is exactly the kind of decision guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the price-to-book (P/B) ratio: share price divided by book value per share — how much investors pay relative to accounting net asset value. Formula: P/B = Share Price / Book Value Per Share. WHEN TO USE: Use for valuing asset-heavy or financial companies where book value is a meaningful anchor; P/B < 1 can indicate undervaluation or low returns on assets. WHEN NOT TO USE: Do NOT use for asset-light businesses (intangibles make book value meaningless) or where book value is negative. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { pb_ratio: number (e.g. 1.4 = 1.4x), inputs }. PARAMETERS: share_price (required): Current share price, e.g. 45.00. Must be > 0. book_value_per_share (required): Book value per share (shareholders’ equity / shares), e.g. 32.00. Must be > 0 for a meaningful ratio.
| Name | Required | Description | Default |
|---|---|---|---|
| share_price | Yes | Current share price, e.g. 45.00. Must be > 0. | |
| book_value_per_share | Yes | Book value per share (shareholders’ equity / shares), e.g. 32.00. Must be > 0 for a meaningful ratio. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/destructive annotations, the description discloses pure deterministic calculation, no side effects, no network/storage access, identical outputs for identical inputs, and explicit error behavior on division by zero or non-finite inputs. This is rich behavioral context.
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 well-organized with clear labeled sections: formula, when to use, when not to use, behavior, returns, and parameters. Every section earns its place and the most important information is front-loaded.
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?
Despite having no output schema, the description explains the return shape as a JSON object with pb_ratio and inputs. It also covers error conditions, parameter constraints, and use context, making it complete for an agent to invoke 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 coverage is 100% and the parameter text in the description largely duplicates the schema descriptions. The formula and financial rationale add context, but individual parameter meanings are already fully documented in the schema, so no significant extra semantic value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Calculate the price-to-book (P/B) ratio' with the exact formula. It is clearly differentiated from the sibling ratio calculators by naming its precise financial definition and output.
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?
Explicit WHEN TO USE and WHEN NOT TO USE sections give strong context: use for asset-heavy or financial companies, avoid for asset-light businesses or negative book value. It does not name alternative sibling tools directly, but the conditions are clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate the price-to-earnings (P/E) ratio: share price divided by earnings per share — how much investors pay per unit of earnings. Formula: P/E = Share Price / EPS. WHEN TO USE: Use for relative valuation against peers, sector averages, or a company’s own history. Higher P/E = market expects higher growth. WHEN NOT TO USE: Do NOT use when EPS is negative or near zero (ratio becomes meaningless), and prefer forward P/E for growth companies. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { pe_ratio: number (e.g. 18.5 = 18.5x), inputs }. PARAMETERS: share_price (required): Current share price in currency units, e.g. 45.00. Must be > 0. earnings_per_share (required): Earnings per share (trailing or forward), e.g. 2.43. Must be > 0 for a meaningful ratio.
| Name | Required | Description | Default |
|---|---|---|---|
| share_price | Yes | Current share price in currency units, e.g. 45.00. Must be > 0. | |
| earnings_per_share | Yes | Earnings per share (trailing or forward), e.g. 2.43. Must be > 0 for a meaningful ratio. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states the calculation is deterministic, idempotent, non-destructive, and free of side effects, which reinforces and extends the annotations. It also discloses error behavior for division by zero or non-finite inputs, adding useful operational detail.
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 well-organized with labeled sections and every sentence adds substance. It covers purpose, usage, behavior, return format, and parameters without unnecessary 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?
Despite no output schema, the description explicitly defines the return shape, parameter constraints, and edge-case behavior. Everything an agent needs to invoke this tool correctly and interpret its result is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description mostly repeats the same parameter descriptions, examples, and positivity constraints found in the schema. The formula and ratio interpretation add context, but little new parameter-specific meaning is provided.
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 the exact metric, gives the formula, and explains what the ratio represents. It is clearly distinguishable from the sibling ratio calculators because it states the specific inputs and output.
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?
Explicit WHEN TO USE and WHEN NOT TO USE sections tell an agent exactly when this ratio is appropriate and when to avoid it, including the meaningful alternative of forward P/E for growth companies. This provides strong decision guidance beyond the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate return on assets (ROA): net income divided by average total assets — how efficiently a company converts its asset base into profit. Formula: ROA = Net Income / Average Total Assets. WHEN TO USE: Use to measure management’s efficiency in deploying all assets, independent of how they are financed. WHEN NOT TO USE: Do NOT compare ROA across industries with different asset intensity; use ROIC for a cleaner operating view. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { return_on_assets: decimal (e.g. 0.08 = 8%), return_on_assets_pct: number (e.g. 8.0), inputs }. PARAMETERS: net_income (required): Net income after tax, e.g. 84000. May be negative. begin_total_assets (required): Total assets at period start, e.g. 1000000. Must be > 0. end_total_assets (required): Total assets at period end, e.g. 1100000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| net_income | Yes | Net income after tax, e.g. 84000. May be negative. | |
| end_total_assets | Yes | Total assets at period end, e.g. 1100000. Must be > 0. | |
| begin_total_assets | Yes | Total assets at period start, e.g. 1000000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful detail beyond those: 'pure deterministic calculation — no side effects, no network or storage access' and specific error behavior for division by zero or non-finite inputs. None of this contradicts the annotations, and it gives the agent concrete expectations about side-effect-free execution and error handling.
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 well-structured with clear section labels: definition, formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS. The core definition is front-loaded, and every section adds distinct value — no filler or repetition. It is longer than a minimal description, but each sentence earns its place by addressing a specific decision or execution concern.
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 there is no output schema, the description fully compensates by specifying the exact JSON return shape: '{ return_on_assets: decimal, return_on_assets_pct: number, inputs }' with examples. It also covers parameter requirements, mathematical semantics, edge-case behavior, and usage boundaries. An agent has everything needed to select and correctly invoke this tool without opening sibling definitions.
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 repeats the schema property explanations but adds conceptual value by clarifying how the parameters produce the result: the formula 'ROA = Net Income / Average Total Assets' implicitly maps begin_total_assets and end_total_assets to the average assets concept. It also labels requiredness and provides examples, reinforcing the schema without requiring the agent to infer the formula relationship.
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 opens with a specific, unambiguous definition: 'Calculate return on assets (ROA): net income divided by average total assets' and includes the formula. This clearly distinguishes it from sibling ratio tools such as ROIC, ROE, and net margin, and explicitly names ROIC as the alternative for a different view. The purpose is fully self-contained.
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 contains explicit 'WHEN TO USE' and 'WHEN NOT TO USE' sections. It states when to use ROA (measuring management efficiency in deploying all assets) and when not to (comparing across different asset-intensity industries), and it names the alternative tool: 'use ROIC for a cleaner operating view.' This is direct, decision-ready guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate return on capital employed (ROCE): EBIT divided by capital employed (total assets minus current liabilities) — return generated by the capital actually deployed in the business. Formula: ROCE = EBIT / (Total Assets - Current Liabilities). WHEN TO USE: Use to compare profitability across companies with different capital structures — EBIT (pre-financing) over all capital employed. WHEN NOT TO USE: Do NOT use when capital employed is near zero or negative; prefer ROIC for after-tax operating returns. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { return_on_capital_employed: decimal (e.g. 0.22 = 22%), return_on_capital_employed_pct: number (e.g. 22.0), inputs }. PARAMETERS: ebit (required): Earnings before interest and taxes, e.g. 220000. May be negative. total_assets (required): Total assets, e.g. 1200000. Must be > 0. current_liabilities (required): Total current liabilities, e.g. 200000. Must be >= 0.
| Name | Required | Description | Default |
|---|---|---|---|
| ebit | Yes | Earnings before interest and taxes, e.g. 220000. May be negative. | |
| total_assets | Yes | Total assets, e.g. 1200000. Must be > 0. | |
| current_liabilities | Yes | Total current liabilities, e.g. 200000. Must be >= 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool is a pure deterministic calculation with no side effects, no network or storage access, idempotency, and fixed behavior for identical inputs. It also discloses error handling for division by zero and non-finite inputs, adding substantial behavioral detail beyond 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 long but every section earns its place: formula, usage guidance, behavioral guarantees, return shape, and parameter recap. It is well-structured with clear labels and front-loads the core definition before the supporting details.
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 three-parameter calculation tool with no output schema, the description fully covers inputs, constraints, calculation semantics, return value shape, examples, and edge-case behavior. An agent has everything needed to invoke it correctly and interpret the result.
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 three parameters with the same constraints and examples. The description adds the ROCE formula linking total_assets and current_liabilities into capital employed, but it repeats most parameter detail rather than adding new meaning.
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 calculation (ROCE) with a clear formula and explains the economic meaning: return generated by capital actually deployed. This distinguishes it from sibling ratio tools like ROE, ROA, and ROIC by specifying the exact inputs and the pre-financing EBIT basis.
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?
Includes an explicit WHEN TO USE section (comparing profitability across different capital structures) and a WHEN NOT TO USE section that names the preferred alternative (ROIC) and the conditions that rule out ROCE (near-zero or negative capital employed). No ambiguity remains about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate return on equity (ROE): net income divided by average shareholders’ equity — the return earned on the owners’ invested capital. Formula: ROE = Net Income / Average Shareholders’ Equity. WHEN TO USE: Use to assess how well management generates returns for shareholders; decompose via DuPont (margin x turnover x leverage) for drivers. WHEN NOT TO USE: Do NOT use when equity is small or negative (distress / heavy buybacks) — ROE explodes or inverts and misleads. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { return_on_equity: decimal (e.g. 0.15 = 15%), return_on_equity_pct: number (e.g. 15.0), inputs }. PARAMETERS: net_income (required): Net income after tax, e.g. 150000. May be negative. begin_equity (required): Shareholders’ equity at period start, e.g. 950000. Must be > 0. end_equity (required): Shareholders’ equity at period end, e.g. 1050000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| end_equity | Yes | Shareholders’ equity at period end, e.g. 1050000. Must be > 0. | |
| net_income | Yes | Net income after tax, e.g. 150000. May be negative. | |
| begin_equity | Yes | Shareholders’ equity at period start, e.g. 950000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description states 'pure deterministic calculation — no side effects, no network or storage access' and specifies error behavior for division by zero or non-finite inputs. This adds substantial transparency about execution characteristics and edge cases.
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 well-structured with clear sections (formula, WHEN TO USE, WHEN NOT TO USE, BEHAVIOUR, RETURNS, PARAMETERS) and front-loads the core definition and formula. Every sentence serves a purpose, covering usage, behavior, output format, and constraints without redundancy or 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?
Despite having no output schema, the description explicitly documents the return object structure ('{ return_on_equity: decimal, return_on_equity_pct: number, inputs }') and provides examples. It also covers parameter requirements, edge cases, and usage boundaries, fully equipping an agent to 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?
The input schema already provides 100% coverage with descriptions and constraints for all three parameters. The description's PARAMETERS section essentially restates these, adding only examples and confirming the constraints already present in the schema. It does not introduce meaningfully new semantic information, so the baseline of 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 states a specific verb and resource: 'Calculate return on equity (ROE)' with the precise formula 'net income divided by average shareholders’ equity'. It clearly distinguishes this from sibling ratio tools by including the formula and the economic meaning of the metric.
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 explicitly provides a 'WHEN TO USE' section ('assess how well management generates returns for shareholders') and a 'WHEN NOT TO USE' section ('Do NOT use when equity is small or negative'), giving concrete conditions and cautioning against misleading outputs. It also suggests DuPont decomposition for deeper analysis, which orients the agent toward appropriate follow-up.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate return on invested capital (ROIC): NOPAT divided by invested capital — the after-tax operating return on capital invested in the business. Formula: ROIC = NOPAT / Invested Capital. WHEN TO USE: Use to assess value creation: ROIC above the cost of capital (WACC) creates value; below it destroys value. Core metric for investors. WHEN NOT TO USE: Do NOT use if you lack a clean NOPAT or invested capital figure — inconsistent definitions make ROIC incomparable. BEHAVIOUR: pure deterministic calculation — no side effects, no network or storage access; idempotent and non-destructive; identical inputs always produce identical outputs. Division by zero or non-finite inputs returns an explicit error instead of a number. RETURNS: JSON object { return_on_invested_capital: decimal (e.g. 0.18 = 18%), return_on_invested_capital_pct: number (e.g. 18.0), inputs }. PARAMETERS: nopat (required): Net operating profit after tax = EBIT x (1 - tax rate), e.g. 180000. May be negative. invested_capital (required): Invested capital (equity + debt - cash, or operating assets - operating liabilities), e.g. 1000000. Must be > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| nopat | Yes | Net operating profit after tax = EBIT x (1 - tax rate), e.g. 180000. May be negative. | |
| invested_capital | Yes | Invested capital (equity + debt - cash, or operating assets - operating liabilities), e.g. 1000000. Must be > 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, it discloses deterministic behavior, no side effects, idempotency for identical inputs, and explicit error handling for division by zero or non-finite inputs. It also describes the return shape, which is not covered by an output 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?
The description is well-organized with clear headings and front-loaded formula/definition. It is somewhat repetitive because the PARAMETERS section duplicates schema descriptions, but the overall structure earns its 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?
With no output schema, the description explains the exact JSON return shape, including example decimal and percentage forms. Combined with parameter coverage, error behavior, and usage guidance, nothing needed 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 coverage is 100% and the description's PARAMETERS section largely repeats the schema wording and examples. It adds no material meaning beyond the schema, so the baseline score of 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 opening sentence states a specific verb and resource: 'Calculate return on invested capital (ROIC): NOPAT divided by invested capital' and gives the formula. This clearly distinguishes it from the sibling financial metric calculators.
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 contains explicit WHEN TO USE guidance (assess value creation relative to WACC) and explicit WHEN NOT TO USE guidance (lack of clean NOPAT or invested capital). The value-creation context helps an agent decide when this metric is relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Add one secure layer between your agents and this server.
Each tool calculates a distinct financial metric with its own formula, inputs, and output. Even similarly named return-on-capital tools (ROA, ROE, ROCE, ROIC) are clearly differentiated by their denominators and described use cases.
All 12 tools follow the exact same calculate_<metric_name> snake_case pattern. The verb is consistent and metric names map directly to the formulas, making the set highly predictable.
Twelve tools is a well-scoped size for a financial ratio calculator covering profitability, return, valuation, and dividend metrics. Each tool addresses a distinct calculation and none feel redundant or unnecessary.
The tool surface covers core profitability margins, return ratios, EPS, dividend yield, payout ratio, P/E, and P/B. Minor gaps exist such as price-to-sales, EV/EBITDA, or EBITDA margin, but the primary domain of profitability and market valuation is well represented.