nzxplorer-mcp

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

Annotations already cover the non-destructive, read-only, idempotent behavior, so the bar for added disclosure is lower. The description adds meaningful context about the content returned (resolutions, votes, pass/fail, support percentages) and the NZX scope, without contradicting 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?

Two short sentences with no filler or redundancy: the first states what the tool returns, and the second gives the use case. The key scoping element 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?

Given simple parameters, an output schema, and annotations that establish read-only/idempotent behavior, the description covers everything needed to invoke the tool correctly and interpret its purpose. There is no obvious missing context for this scope.

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

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

Schema description coverage is 100%, so the schema already documents ticker and year. The description adds no meaning beyond 'voting data for an NZX company,' which only reinforces the obvious ticker parameter, so it stays at 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 names a specific verb ('Get'), a specific resource ('AGM resolution voting data'), and a scope ('for an NZX company'). It also lists the concrete data elements (votes for/against/abstain, pass/fail, support percentages), which distinguishes it from related governance siblings like get_governance_scores and get_board_changes.

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 gives an explicit intended use: 'Use for governance and shareholder activism analysis.' It does not name exclusion conditions or sibling alternatives, so an agent must infer when another tool is more appropriate, but the stated context is clear enough for a first selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds what the tool shows (report URLs, financial year, extraction status), but does not discuss pagination, data freshness, or other behavioral details. This is acceptable but not rich.

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, zero filler, and the core function is stated first. The usage guidance is a natural second sentence with no redundancy.

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

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

For a simple read-only tool with full schema coverage, clear annotations, and an output schema, the description is complete enough. An agent can confidently select and invoke it without needing further context.

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. The description does not add meaningful parameter semantics beyond that baseline.

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

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

Description states a specific verb ('Get') and resource ('annual and interim report URLs') and names the returned content (URLs, financial year, extraction status). It is clearly distinct from sibling tools like get_earnings or get_financials.

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

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

Explicitly says 'Use this when asked about a company's annual reports, filings, or report history.' It does not mention when not to use it or name alternative tools, but the stated trigger is clear enough for most cases.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes some value by specifying the breadth and structure of returned events (amounts, pricing, dilution), but says nothing about permissions, data currency, coverage gaps, or result limits beyond what the schema states.

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 tight sentences, front-loaded with the core verb+resource and then the payload contents. The closing clause 'Structured events across NZX issuers' is mildly redundant given 'NZX company' already appears, but overall there is little waste.

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

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

An output schema exists so return values need not be explained, and all five parameters are fully documented in the schema. The description covers scope (NZX issuers) and content classes, which is adequate; only cross-tool routing and edge cases (e.g., no raises found, date-range behavior) are unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents ticker, type, year, limit, and buybacks. The description's list of raise types loosely mirrors the type parameter's allowed values but adds no syntax, format, or interaction detail (e.g., how 'buybacks' overlaps with type=buyback). Baseline 3 applies 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?

States a specific verb+resource ('Get capital raise history') and enumerates the event classes it returns (placements, rights issues, SPPs, IPOs, bonds, buybacks, DRPs), which distinguishes it from generic financial tools like get_financials or get_dividends. It does not, however, explicitly distinguish itself from the closely named sibling get_capital_raise_sentiment, which is the tool most likely to be confused with it.

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?

There is no guidance on when to use this tool versus alternatives such as get_capital_raise_sentiment, get_takeovers, or get_dividends. Usage is only implied by the data types listed; no prerequisites, exclusions, or routing hints are 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, so the safety profile is covered. The description adds that the result 'can include' optional categories, but it does not clarify default behavior when the include parameter is omitted or explain any other behavioral nuances such as pagination or response size.

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

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

The description is a single sentence that front-loads the core action and resource, then lists the relevant optional content. There is no filler or redundant elaboration; every clause contributes useful information.

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

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

Given the output schema exists and annotations carry the safety profile, the description is mostly adequate for a simple read tool. However, for an agent choosing among many similar sibling tools, it would benefit from clarifying how the aggregate response relates to specialized getters and what happens when the include parameter is not supplied.

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

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

Schema description coverage is 100%, so the ticker and include parameters are already fully documented with examples. The description reinforces the include categories but adds no meaning beyond the schema, such as default values, validation rules, or behavior when include is absent.

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 a specific verb and resource: 'Get detailed info for a specific NZX company by ticker.' It also lists the data categories included (directors, financials, governance score, stock price), which helps distinguish it from narrower sibling tools like get_directors or get_financials, though it does not explicitly name those alternatives.

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 that this tool is appropriate when you need broad company detail by ticker, and the 'Can include' phrasing hints at selecting categories. However, it does not explicitly state when to prefer this aggregate tool over the many specialized getter siblings, nor does it mention any exclusions or fallback 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, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it shows what event types are included (upgrades, downgrades, outlook changes) and warns about limited company coverage. It does not mention pagination or empty results, but that is partly covered by the output schema and parameter descriptions.

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 tightly written sentences. The first sentence states the purpose, and the second adds content detail and a valuable coverage caveat without wasted words or repetition of schema fields.

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 read-only look-up tool with one required parameter, a fully described schema, and an output schema, the description is complete. It explains the domain, the included data types, and the sparse coverage for NZX companies. Nothing an agent needs in order to decide whether and how to call this tool 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%, with every parameter already documented. The description does not add substantial parameter-specific meaning beyond the schema; it merely reinforces the domain context. A baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and resource ('Get credit rating history for an NZX company') and immediately clarifies the subject matter by naming the agencies and event types. This clearly distinguishes it from other NZX company tools like get_financials or get_stock_prices, even without an explicit sibling comparison.

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 states clear context: this is for NZX company credit rating history, covering four named agencies. The caveat that only ~20 NZX companies have credit ratings helps the agent set expectations and avoid calling it for tickers likely to have no data. It does not name alternatives, but no direct alternative exists among the siblings, so the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds output composition but does not reveal behavioral nuances like data freshness, market-hours limitations, or failure behavior. It is adequate but not enriched beyond what annotations already provide.

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 focused sentences: the first states the resource and what it returns, the second gives concrete usage triggers. There is no filler and the essential 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?

For a read-only tool with one optional parameter, full schema coverage, and an output schema present, the description fully supports selection and invocation. Nothing critical is missing for an agent to decide when to call it.

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% for the single optional 'days' parameter, including minimum, default, and usage guidance ('Use 1 for last trading day, 7 for the week'). The description adds no new parameter semantics, but none are needed because the schema fully documents it.

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 specifies a precise verb and resource: it gets a market-wide NZX digest covering all active issuers, and enumerates contents (price moves, breadth, announcements, insider trades, dividends, board changes, AI summary). This clearly distinguishes it from sibling company-specific tools like get_stock_prices or get_dividends.

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 gives invocation triggers: 'when asked about overall market conditions, today's market, what happened on the NZX, or market summary.' It does not explicitly mention when not to use it or name alternatives, but the market-wide scope and trigger phrases are clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context by listing the exact response contents: ex-date, payment date, DPS, imputation %, DRP availability, safety score, cut probability, and payout ratio charts. This goes beyond the structured hints.

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 sentences: the first gives the core purpose and the second lists key outputs with no filler. It is front-loaded and information-dense without being bloated.

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

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

With an output schema present and annotations covering safety, the description is sufficient for an agent to understand what the tool returns and when to call it. Minor gaps like default time ranges or pagination behavior are not critical here.

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 all four parameters are already documented. The description does not add parameter-level detail beyond what the schema provides, so the baseline of 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 states a specific verb ('Get'), resource ('dividend history'), and scope ('NZX company'), and enumerates the exact data fields returned. This makes it easy for an agent to distinguish from sibling tools like get_earnings or get_financials.

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

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

The description clearly scopes the tool to dividend history and dividend-related company page metrics, which provides strong context for when to use it. It does not explicitly name alternatives or exclusions, but the context is specific 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.

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

Annotations already cover read-only, idempotent, and non-destructive nature, and the description adds context by specifying the source (full-year and half-year announcements) and the inclusion of management guidance, which is not apparent from annotations. No contradictions.

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 sentences with no fluff wants. It front-loads the primary resource and then lists included metrics, which is efficient and structured for quick scanning.

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

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

Given the tool's moderate complexity, full schema coverage, and an output schema that likely defines return structure, the description is sufficient. It provides essential behavioral context (source, included metrics) without over-explaining. No critical gaps.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add extra meaning beyond the schema; it merely implies the tool uses ticker and filters. 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?

States a specific verb ('Get') and resource ('earnings results for an NZX company'), and lists key fields included (revenue, net profit, etc.). It differentiates clearly from siblings such as get_financials and get_dividends, but does not explicitly name or differentiate against a specific sibling tool beyond the general resource.

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 by indicating it is for earnings results from announcements, but it does not explicitly state when to use this tool versus alternatives like get_financials or get_metrics. No exclusions or conditions are given.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful scope context about what data categories are returned, but discloses nothing extra about behavior (e.g. missing-data handling, coverage limits, sourcing).

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, front-loaded with purpose followed by a compact domain inventory. The parenthetical lists are information-dense rather than filler, though the enumeration is long enough to be slightly list-heavy.

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

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

With an output schema present, the description need not explain return values, and it adequately scopes the data domains covered. The main gap is absent routing guidance among the many ESG-adjacent siblings, which is a usage rather than a completeness concern.

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% with both parameters documented (ticker as NZX symbol, year as fiscal-year filter), so the schema carries the semantics. The description adds no format or filtering nuance beyond that, making the baseline 3 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?

States a specific verb+resource ('Get ESG data for an NZX company') and enumerates the covered domains (emissions, diversity, safety, reporting standards), which lets an agent distinguish it from siblings like get_esg_xbrl or get_esg_disclosure_benchmark. It does not explicitly name any sibling it is not, 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?

No when-to-use or when-not-to-use guidance and no reference to alternatives such as get_esg_disclosure_gap or get_esg_target_credibility. Usage is only implied by the domain description, leaving the agent to infer routing from sibling names alone.

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 what content is included and that filtering is possible, which is useful but not deeply behavioral.

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 compact sentences with the action and scope front-loaded. No filler or redundant restatement of the tool name.

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 read-only, idempotent tool with a fully documented parameter schema and an output schema, the description adequately conveys what the tool returns and how it can be filtered. It lacks only explicit default/alternative guidance, which is not essential here.

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 echoes the statement type and year range parameters but adds no format, default, or constraint details beyond what the schema already provides.

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

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

States a specific action (get financial statements) and resource (NZX company), enumerates the included statements and ratios, and mentions filtering. It doesn't explicitly distinguish itself from financial siblings like get_earnings or get_metrics, but the scope is still clear.

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

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

No guidance on when to use this tool instead of alternatives. With many financial sibling tools (get_earnings, get_metrics, get_revenue_segments), the agent receives no routing signal beyond the general description of financial statements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by defining GRS as a 0-100 scale composed of six specific components and by indicating filtering capabilities. No contradiction with annotations exists.

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 sentences with no filler. It front-loads the core purpose and then immediately provides the most useful selection details: scale, components, and filter categories. Every sentence adds value.

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

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

With an output schema present, no required parameters, and all seven parameters documented in the schema, the description is sufficient for a correct call. It covers what the tool returns at a conceptual level and the filtering dimensions. Nothing necessary for selection or invocation appears 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 parameter meanings are already well documented. The description adds marginal value by explaining that sector, rating, and score range are filter options and by framing the 0-100 scale relevant to min_score/max_score. This meets the baseline but does not go beyond the schema in meaningful new detail.

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 and resource: 'Get Governance Risk Scores (GRS) for NZX companies.' It also explains the score scale and its six components, which makes the tool's scope immediately clear. The resource is unique among the sibling tools (e.g., distinct from get_credit_ratings or get_esg_data), so an agent can select it without opening the schema.

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

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

The description implies usage context by naming the domain (governance risk for NZX firms) and listing available filters, but it does not explicitly state when to use this tool versus alternatives or when not to use it. There is no mention of exclusions or related sibling tools, so the guidance is adequate but not direct.

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. The description adds valuable behavioral context beyond annotations: it specifies the output content (funds, market value, percentage) and the data coverage window (Dec 2018 - Sep 2022), which is a meaningful limitation. 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?

The description is two tight sentences with no fluff. It front-loads the core purpose, then adds output details and the date range. Every sentence earns its place.

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

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

For a low-complexity tool with a full input schema, strong annotations, and an output schema, the description is complete. It covers what the tool returns and an important data availability limitation. Nothing critical is missing for an agent to invoke 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%, so the baseline is 3. The description does not add much beyond the schema for the ticker and date parameters, but it does clarify the overall data scope and time coverage. Since the schema already documents each parameter, this is adequate.

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

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

The description clearly states a specific action ('Get KiwiSaver fund holdings') and resource ('an NZX company'), then specifies exactly what is shown: funds, market value, and percentage. This distinguishes it from sibling tools like get_shareholders or get_substantial_holders without needing to open 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?

There is no guidance on when to use this tool versus alternatives. It does not mention exclusions or conditions, such as when to prefer get_shareholders or get_substantial_holders. The date coverage is useful context but not usage direction.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds meaningful context: the set of executives returned (CEO/CFO/COO/CTO and others), included attributes (tenure, biographies, education, profile links), and that profile data appears only where linked to shared.people.

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

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

Four short sentences, front-loaded with the core purpose, then return contents and filtering. Mildly redundant ('15 normalized roles' restates the schema enum) but no wasted padding.

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

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

With an output schema present, the description needn't detail return values, and it still characterizes them well. Required-vs-optional parameters are clean and explained. Nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, and both ticker and role are documented in the schema with examples and an enumerated role list. The description's mention of '15 normalized roles' and the role filter largely repeats what the schema already provides, so this sits at the baseline.

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

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

States a specific verb ('Get') and resource ('management team (C-suite executives) for an NZX company'), and scopes it to senior executives rather than the board or general staff. An agent can distinguish this from get_directors and get_executive_compensation without opening a schema.

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

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

Usage is implied via the role filter example ('Filter by role (e.g. CEO, CFO)'), but there is no explicit statement of when to reach for this tool versus siblings like get_team_members or get_directors, nor any prerequisite noted. Adequate but leaves routing to inference.

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 it read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavioral context beyond that — notably the composite_signal concept (multi-signal patterns like insider selling + earnings miss) that explains what the feed surfaces. It omits pagination/rate-limit behavior, but with annotations and an output schema the gap is minor.

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

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

Front-loads the core purpose in the first clause and the 13-type enumeration is genuinely useful for matching agent queries. The long type list and example-question run are somewhat dense but each element earns its place by expanding retrieval coverage.

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 annotations, full schema coverage, and an output schema present, the description is complete enough to call the tool correctly and understand what it returns. The main missing piece is guidance on when to choose this unified feed versus single-domain siblings, which is a usage-guideline gap rather than a completeness failure.

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 fully documents all six parameters including defaults and example values. The description's example questions loosely map to the 'days' parameter but add no syntax or format detail beyond the schema. 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?

States a specific verb and resource ('Get the Market Intelligence Feed') and defines it as 'a unified stream of all NZX market events', then enumerates the 13 signal types it aggregates. This clearly distinguishes it from single-domain siblings like get_insider_trades, get_technical_signals, or get_credit_ratings.

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?

Provides concrete example questions ('what happened on the NZX today/this week?', 'any recent insider trades?', 'market activity for AIR') that anchor when to use it. However, it never names alternatives or states when to prefer a narrower sibling tool over this unified feed, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the breadth of metrics (46 ratios across categories), but it doesn't describe behavioral details like default modes, list-vs-single behavior, or result shapes beyond what the schema already provides.

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 efficient sentences with no filler. The core function is front-loaded, and the ratio categories are compactly listed with representative examples. Every part of the description earns its place.

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

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

Given the read-only annotations, full schema parameter coverage, and presence of an output schema, this definition gives an agent enough to select and call the tool correctly. The main gap is potential overlap with siblings like get_financials or get_performance, though the metric categories and 'screening or comparison' guidance mostly disambiguate it.

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 parameters are already well documented there. The description adds context about the ratio families that may be relevant to sorting/filtering, but it does not add new meaning to individual parameters like mode, sort, year, or limit. 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 ('financial metrics/ratios for NZX companies'), specifies the verb 'get', and enumerates ratio categories and example metrics. It is specific about what the tool returns, but it doesn't explicitly differentiate itself from similar siblings like get_financials, get_earnings, or get_performance.

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?

'Use for screening or comparison' gives a clear intended use case, and the ratio listing supports that framing. However, it does not name alternatives or state when not to use this tool instead of a sibling, so it falls short of full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by listing the returned metrics, which informs the agent about the output shape. It does not contradict annotations, and it adds value beyond 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?

The description is two sentences with no filler. It front-loads the core purpose and metric list, then adds the usage context. Every word earns its place, making it efficient and well-structured.

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

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

Given the single parameter, read-only nature, and existence of an output schema, the description provides all necessary context: what it does, what it returns, and when to use it. No critical information is missing for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, with the parameter 'ticker' already described as 'NZX ticker symbol'. The description adds nothing further about the parameter's format, constraints, or examples. Since the schema fully covers semantics, a baseline score of 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 states a specific verb ('Get') and resource ('stock performance metrics for an NZX company') and enumerates concrete metrics (returns 1d-5y, alpha vs NZX50, volatility, 52-week range, market cap). This clearly distinguishes it from siblings like get_stock_prices or get_metrics, which cover different data.

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 gives an explicit use case: 'Use for performance comparison and pay-for-performance analysis.' It does not explicitly name alternatives or state when not to use it, but the stated use case is clear and sufficient for an agent to decide. A minor gap is the lack of explicit exclusions or alternative tool references.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the output content (segment types, fields, and NZD thousands units), which helps the agent anticipate what the tool returns beyond what the structured annotations provide.

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

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

Three sentences with the action and resource front-loaded, followed by return data and usage triggers. Every sentence earns its place with no redundancy, making it appropriately sized and efficiently structured.

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

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

With an output schema present and annotations covering safety, the description provides the trigger phrases, return scope, and units. This is complete for an agent to select and invoke the tool correctly without missing prerequisites or caveats.

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 covers all 4 parameters with descriptions (ticker, type, year, limit). The description reinforces the type values and ticker format but adds no new parameter meaning beyond the schema, 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?

Explicitly states the verb 'Get' and the resource 'revenue segment breakdown' for an NZX company, and clarifies the return data (operating/geographic/product segments with revenue, profit, assets). This clearly distinguishes it from siblings like get_financials and get_earnings, which cover broader 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?

Provides explicit trigger phrases ('revenue breakdown', 'business segments', 'divisions', etc.) that signal when to use the tool. However, it does not mention when not to use it or recommend alternative tools, so it lacks exclusion guidance despite clear use-case guidance.

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. The description adds that the data is daily history with OHLCV fields, giving useful behavioral context beyond the annotations. It does not discuss adjustment policy or missing-ticker behavior, but those are minor given the annotations and 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 two short sentences with the core operation front-loadedley and no filler or repetition of schema fields. Every sentence contributes to selection or invocation.

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

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

With a full output schema, 100% parameter coverage, and clear annotations, the description is complete for a low-complexity read-only tool. Nothing that an agent needs to call 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 description coverage is 100%, so ticker, from, to, and days are already documented in the input schema. The description adds no parameter-level detail beyond the schema, so the baseline score of 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 and resource: 'Get daily stock price history (OHLCV) for an NZX company.' It names the data format and explicit use cases, which distinguishes it from sibling tools like get_daily_market_wrap and get_technical_signals.

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

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

It explicitly says 'Use for price trends, returns, and technical context,' which gives clear routing guidance. It does not name alternatives or state when not to use it, but the use-case list is sufficient for most selection decisions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it returns structured deal data with specific fields (acquirer, target, offer price, total value, premium, acceptance %, status, timeline) and enumerates the deal types included. It does not mention pagination or default limits, but the schema covers the limit parameter. This is solid value beyond 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?

The description is three sentences with zero waste. The core purpose is front-loaded in the first sentence, the return structure in the second, and the usage triggers in the third. Every sentence earns its place, and the structure is easy to scan.

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 read-only, idempotent tool with a 100% schema-covered parameter set and an output schema, the description is nearly complete. It explains what the tool returns, which deal types are covered, and when to use it. The only minor gap is that it doesn't explicitly state the default limit or pagination behavior, but the schema's 'limit' parameter description covers the default, and the output schema handles return values. This is complete enough for an agent to select and 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 description coverage is 100%, so the schema already documents all five parameters. The description adds the deal-type taxonomy and the trigger phrases, which enrich understanding of the 'deal_type' and 'status' parameters, but it doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate because the schema carries the heavy lifting and the description provides only marginal extra 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 states a specific verb ('Get'), a clear resource ('M&A and takeover activity for an NZX company'), and enumerates the exact deal types covered (takeover offers, mergers, schemes of arrangement, compulsory acquisitions, asset acquisitions). It also lists the structured fields returned, which distinguishes it from sibling tools like get_capital_raises or get_company_detail. The trigger phrases ('takeovers', 'M&A', 'acquisitions', 'hostile bids') further clarify scope.

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 trigger phrases and a clear context ('when asked about...'), which tells an agent when to select this tool. It does not explicitly name sibling alternatives or state when NOT to use it, but the trigger list plus the deal-type enumeration gives strong usage guidance. A small gap: it doesn't contrast with get_capital_raises or get_company_detail, but the specificity of the trigger phrases largely compensates.

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 the list of computed indicators but does not disclose behavioral details such as data freshness, error cases, or dependency on historical data availability. This is adequate given the annotations, but not rich.

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 concise sentences, front-loaded with the action and resource, followed by a compact indicator list and clear use cases. Every sentence earns its place and there is no filler.

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

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

With one required parameter, a full output schema, and safety annotations, the description covers the essential decision points. It lacks explicit differentiation from the sibling tool get_market_signals, which is a minor gap, but overall the definition is complete enough for correct invocation.

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

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

Schema description coverage is 100% and the single 'ticker' parameter is well-documented with examples. The description adds no extra parameter semantics beyond restating the NZX company context, so the baseline score of 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 ('get') and resource ('technical analysis indicators for an NZX company') and enumerates concrete indicator types, making the tool's purpose immediately clear. It does not explicitly contrast itself with sibling tools like get_market_signals, but the detailed indicator list provides enough specificity to identify what this tool returns.

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 gives explicit use cases: 'trading signals, momentum analysis, and technical screening.' This tells an agent when to select the tool, though it does not mention when not to use it or name alternatives, so it falls just short of a 5.

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

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

Annotations already cover read-only, idempotent and closed-world behavior, and the description adds genuinely new context: the response is produced by AI extraction (summary, key figures, sentiment, entities, risk flags) and results are cached when previously extracted. The incomplete example clause weakens but does not undermine this.

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 text is short and front-loads the purpose, but the final sentence is cut off mid-clause ('(e.g. Returns cached results...'), which is a structural defect in an otherwise tight definition.

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

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

An output schema exists, so return values need not be described, and caching is disclosed. Still, the truncation leaves the id format ambiguous and nothing is said about extraction cost or failure behavior on an unknown id.

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?

With a single fully documented parameter at 100% schema coverage, the schema carries the semantics. The description restates that announcement_id must be provided and gestures at an example ('e.g.'), but the example is truncated and adds no usable format guidance.

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 ('Read and analyze a specific NZX announcement') and lists the extracted artifacts, which distinguishes it from search_announcements. However it never names the sibling or explains the read-vs-search split explicitly.

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 word 'specific' and the required announcement_id imply this is the follow-up to an announcement search, and the schema reinforces that the id comes from search results. There is no explicit when-to-use/when-not statement or mention of an alternative tool.

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

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

The description adds valuable behavioral context beyond the annotations: it notes the search covers 2017-present, that most announcements have extracted PDF text (implying some may not be searchable), and that certain AI fields like ai_sentiment are optional ('May also include'). This discloses variability in results and search coverage. It does not contradict any annotations, and the readOnlyHint is consistent with a search operation.

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 and front-loaded: it starts with the core function and scope, then provides usage guidance, and finally enumerates the AI-annotated result fields. It is slightly longer than necessary but every sentence conveys relevant information, and it avoids redundancy with the schema. The organization makes it easy for an agent to quickly grasp the tool's purpose and expected outputs.

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 search tool with six optional parameters and an output schema (which exists but isn't shown), the description covers the key contextual aspects: search scope, date range, and the variety of AI fields returned. It explains that some fields are conditional ('May also include'), which is important for interpreting results. While it doesn't address pagination or error handling, the presence of an output schema reduces the burden on the description, and the overall coverage is sufficient for correct invocation.

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

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

The schema already provides complete descriptions for all six parameters (100% coverage), including details like 'searches both titles and full PDF document text' for the query parameter. The tool description itself does not add further parameter-specific semantics beyond what the schema already states. With full schema coverage, a baseline of 3 is appropriate; the description's focus on result fields is useful context but 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 clearly states the tool performs full-text search across NZX market announcements, specifically searching both titles and full document content. It distinguishes itself from siblings like read_announcement (fetching a specific announcement) and search_companies (searching companies) by emphasizing cross-filing content search. The date range and AI classification outputs further clarify its unique role.

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

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

It explicitly states the intended use: 'Use for finding mentions of specific topics, companies, people, or events across all NZX filings.' This gives clear context, though it doesn't explicitly state when NOT to use it or mention alternative tools. The guidance is strong but could be more explicit about exclusions, such as not using it for fetching a single known announcement.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds only the return shape (a company list with sector and market cap), which duplicates the output schema rather than adding behavior like truncation or ranking.

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 front-loaded sentences with zero filler: purpose first, return shape second. The second sentence is slightly redundant given the output schema, but it costs little.

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?

All params are optional, so an agent needs to know what an empty call does (list all companies? error?), and the description never says whether search is required. With annotations and an output schema already carrying most weight, the remaining gap is the no-argument behavior.

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 documents search, sector, and limit including examples. The description echoes the name/ticker search ('air new zealand' or 'AIR') but adds no meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (search NZX-listed companies by name or ticker) plus what comes back (sector, market cap). It doesn't identify how it differs from close siblings like screen_stocks or get_company_detail, so an agent must infer the boundary.

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

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

No when-to-use or when-not-to-use guidance and no mention of alternatives such as screen_stocks (screening) or get_company_detail (full detail for one company). The name-based lookup use case is only implied by the description's wording.

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