DilutionLens — ASX dilution

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds meaningful behavioral context: it explains the data structure (quarterly vs half-year filers, period_months indicator, operating-only net flow averaged per quarter) and that results are identical to the paid page. This goes beyond the annotations without contradicting them.

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 zero fluff. The main purpose is front-loaded, and the second sentence adds a useful reference point (paid page). Every word contributes, and the structure is efficient.

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

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

For a single-parameter read-only tool with no output schema, the description gives a strong sense of what data to expect: specific rows, period_months semantics, and operating-only net flow. It does not describe the exact output structure, but the coverage is sufficient for an agent to understand the tool's function and call it 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 schema provides 100% coverage for the single parameter 'ticker' with a clear description, including the note that there is no batch form. The tool description adds no parameter-specific information beyond what the schema already states, so it meets the baseline for high 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 states a specific verb and resource: 'Cash, burn and cover history' for one ASX company. It enumerates the exact data rows (4C/5B, 4D/4E) and notes it matches the paid page's cash detail, making the purpose unambiguous and distinct from sibling tools like get_dilution_snapshot or get_options.

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 no explicit guidance on when to use this tool versus alternatives. It does not name any sibling tool or state conditions for selection. The specific scope ('cash runway') implies usage, but without exclusions or comparisons, an agent must infer when this is the right choice.

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, covering the safety profile. The description adds valuable behavioral context: it works without a key, has a ~20 calls/day rate limit, and reveals a contract detail (the JSON key max_dilution_pct remains stable). It also notes it mirrors the free company page, implying a specific data source. These details go beyond the annotations and aid an agent in understanding runtime behavior.

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 compact two-sentence structure with no filler. The first sentence states purpose and metrics, the second conveys the contract note and auth/rate-limit details. Every sentence carries essential information, and the purpose is front-loaded. This is an efficient, well-organized description.

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

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

For a single-parameter tool with no output schema, the description covers the essential operational details: what metrics are returned, the contract key, auth requirement, rate limit, and data source. It lacks explicit units or formatting for the metrics (e.g., currency for market cap), but that is not critical for invoking the tool. It is sufficiently complete for an agent to call it 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% – the ticker parameter already has a clear description ('One ASX ticker code, e.g. BHP. One company per call — there is no batch form.'). The tool description reiterates 'one ASX company' but adds no new syntax or format details. Since the schema fully documents the parameter, the description adds no extra meaning, warranting the baseline 3.

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

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

The description states a specific verb ('get') and a clear resource ('dilution snapshot for one ASX company'), then enumerates the exact metrics returned (risk level, cash cover band, market cap, 12-month raise count, options & rights overhang %). This is specific enough to distinguish from siblings like get_cash_runway or get_options without naming them.

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

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

The description clarifies the tool's scope ('headline dilution metrics') and notes it mirrors the free company page, but it does not explicitly state when to use this tool versus siblings like get_issuance_timeline or get_raise_history. The '~20 calls/day' hint suggests a lightweight snapshot, but no direct alternatives or exclusions are provided. Usage is implied rather than explicitly 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds output scope but no behavioral traits beyond that; it does not contradict the annotations. This is a standard, adequate level given rich 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 sentences, with the core resource and scope front-loaded. The second sentence ('Identical to the paid page's timeline') is somewhat marginal for an agent but not distracting; overall it's concise and structured well.

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?

Without an output schema, the description gives a useful high-level outline of the returned data (dated and cited filings), but it does not specify structure, ordering, or filing types. It is adequate for a single-parameter read-only tool, but gaps remain.

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

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

Schema description coverage is 100% and the ticker parameter is already well documented (one ticker, no batch). The tool description adds nothing beyond the schema, 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 clearly identifies the resource (share-issuance timeline for one ASX company) and the content (every issuance-relevant filing, dated and cited). It is specific and not a tautology, but it does not explicitly differentiate from sibling tools like get_raise_history, so it stops 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 the tool (when you need a company's issuance timeline) and the schema adds a concrete constraint (one company per call, no batch form). However, there is no explicit guidance about alternatives or when not to use it, so it does not fully meet the 4-bar.

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

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

Annotations declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: it discloses the free/keyless tier with a rate limit, explains that a paid key unlocks additional fields (in-the-money value, filing description, as-filed quantities), and notes the output matches free/paid company page blocks. This goes well beyond the structured annotations without contradicting them.

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 dense sentences, each earning its place: scope and contents, free-tier limitations, and paid-tier additions. The core purpose is front-loaded, and the structure makes the free vs paid distinction easy to parse. No fluff or repetition.

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 single parameter and no output schema, the description fully covers what the tool returns and under what conditions, including the data fields and the free/paid behavior differences. An agent has enough information to call it correctly and understand the response shape.

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% — the schema already explains 'one ASX ticker code, e.g. BHP' and 'one company per call — there is no batch form.' The description reinforces 'one ASX company' but adds no new parameter-level meaning beyond what the schema provides. 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 as 'the option and convertible register for one ASX company' and specifies the exact data fields returned (code, security kind, type, exercise price, expiry, quantity). This distinguishes it from sibling tools like get_cash_runway or get_dilution_snapshot, which cover entirely different financial instruments or 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 description clarifies free vs paid API key usage and rate limits (~20 calls/day), but does not explicitly state when to prefer this tool over siblings or provide exclusions. The differentiation from siblings is only implied by the resource type, not by direct comparison or conditions.

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 false, so the safety profile is covered. The description adds useful behavioral context by stating it returns 'every capital raise on record,' implying completeness, and that it matches the paid page's data. This goes beyond the annotations without contradicting them.

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 zero waste. The first sentence front-loads the core purpose and data fields; the second provides a useful equivalence reference. No redundant or filler 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?

For a single-parameter, read-only tool with annotations and a fully described schema, the description is complete. It specifies the output fields, scope, and equivalence, so an agent can call it correctly without missing information. No output schema exists, but the description adequately explains the return content.

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

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

Schema description coverage is 100% and the description adds no parameter-specific meaning beyond what the schema already provides (e.g., 'One ASX ticker code... no batch form'). Since the schema fully documents the only parameter, the baseline of 3 applies; the description does not enhance parameter understanding.

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 ('get') and resource ('raise history') with detailed fields (date, type, amount, issue price, shares issued, brokers, purpose) and scope (one ASX company). This clearly distinguishes it from sibling tools like get_cash_runway or get_dilution_snapshot, which target different financial 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 description implies usage for retrieving raise history but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The sibling tools are not referenced. The only contextual note is 'Identical to the paid page's raise history,' which provides no comparative guidance. Usage is inferred from the tool name and description.

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 readOnly/idempotent/destructive hints, and the description adds substantial behavior beyond them: the 20-row cap with no offset paging, top-of-ordering semantics, the default exclusion of suspended companies matching website behavior, the `suspended_hidden` response field, and the `suspended=include` override. 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?

Three tight sentences plus a compact filter list, with the core purpose first, then limits, then positioning, then the suspended nuance. Every sentence earns its place; the suspended explanation is the longest part but carries unique behavioral information that justifies 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?

For an 8-parameter tool with no output schema, the description covers limits, default behavior, overrides, and one response field (suspended_hidden). The only minor gap is the absence of any indication of which columns/fields the returned rows contain — though 'screen' implies company rows, the full return shape is unspecified.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value for the suspended parameter by explaining the default-exclusion behavior and the response counter, which the schema only partially conveys. The filter list groups the parameters coherently, though it mostly mirrors schema names for the other seven 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?

States a specific verb ('Screen') and resource ('the ASX universe') with named dimensions (dilution risk, cash cover, market cap, industry). The phrase 'A discovery tool, not an extract' plus the sibling names (get_cash_runway, get_dilution_snapshot, etc.) make it unmistakably distinct: this is a universe-wide screener while the siblings are per-company data lookups.

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 positions the tool as a discovery tool for screening the universe, which implies it is for breadth-first exploration rather than targeted retrieval. It also states what it is not ('not an extract') and its hard limit (at most 20 rows, no paging). It does not name a specific sibling alternative, but the get_* sibling set makes the boundary clear enough.

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