DilutionLens

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

Annotations already cover safety with readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful context that the data is quarterly and identical to the paid page's cash detail. It does not disclose return format or pagination, but those are less critical given the strong annotation coverage.

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 two short sentences with no filler, and the core resource and scope are front-loaded. The second sentence about the paid page is optional but adds a provenance signal without bloating the definition. The paid-page reference may be slightly opaque to an agent without that external context.

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 one-required-parameter, read-only, idempotent tool, the description supplies the essential facts: what data is returned and for which company type. There is no output schema, so exact fields are not enumerated, but the high-level history terms are sufficient for selecting and invoking the tool. No nested objects or enums add complexity.

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 fully documents the ticker parameter with an example and the one-company-per-call limitation at 100% coverage. The description does not add any new parameter-level semantics beyond restating the single-company scope. A baseline of 3 is appropriate when the schema carries the parameter burden.

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

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

The description identifies a specific resource—quarterly cash, burn, and cover history for one ASX company—and is clearly distinct from sibling tools covering dilution, issuance, options, and raises. The tool name and title supply the verb 'get', making the operation unambiguous. It is concise and not tautological.

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 does not state when to prefer this tool over alternatives or mention any exclusionary conditions. The one-company constraint is noted, but the 'no batch form' detail lives in the parameter schema rather than the description. No comparison to sibling tools is provided.

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.