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, and destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying that the output includes 'dates and reasons', which is useful for understanding what the tool returns. No contradictions 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?

Two sentences with no redundancy. The main purpose is front-loaded, and the additional detail about dates and reasons is concise and relevant. Every word 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?

The tool has 5 parameters, 1 required, and an output schema. The description covers what it does and the nature of the output (dates and reasons). It does not mention pagination or usage scenarios, but given the output schema and annotations, it is sufficiently complete for an agent to understand the tool's purpose and basic call pattern.

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 parameters (to, from, limit, action, ticker) are already documented in the schema. The description does not add extra meaning beyond mentioning that results include dates and reasons, which relates to the from/to parameters but does not expand on syntax or format. Baseline 3 is appropriate given the high coverage.

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

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

The description clearly states the specific verb 'Get', the resource 'director appointment, resignation, and retirement events', and the scope 'for an NZX company'. It further clarifies that it shows 'board composition changes over time with dates and reasons', distinguishing it from siblings like get_directors (which likely lists current directors) and get_director_detail (specific director info).

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 historical board changes via 'over time', but does not explicitly mention alternatives or when not to use it. It lacks explicit routing to siblings like get_directors for current composition, so guidance is only implied, not stated.

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 indicate read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context beyond annotations: the dataset is described as ~11,700 structured events across 131 issuers, and that it includes amounts, pricing, and dilution. This gives an agent a sense of data scope and content 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 sentences with no filler. The first sentence states the primary purpose up front, and the second sentence adds valuable detail about event types and dataset scale. Every phrase contributes to understanding the tool.

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 full parameter descriptions in the schema, the description is largely complete for invocation. It clearly identifies the resource and what is included. The only minor gap is that it does not clarify the relationship between the 'buybacks' filter parameter and the 'type=buyback' option, but this is not essential for basic use.

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 input schema already documents all five parameters including type values, year format, and limit. The description does not add meaning beyond the schema; it mentions event types and pricing information, but these do not clarify parameter formats or relationships.

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 uses a specific verb ('Get') and resource ('capital raise history for an NZX company'), and clarifies the scope by enumerating event types such as placements, rights issues, SPPs, IPOs, bonds, buybacks, and DRPs. This clearly distinguishes it from sibling tools like get_dividends or get_takeovers.

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 clear context: this is for capital raise history of an NZX company, which implies when it should be used. It does not explicitly name alternative tools or exclusion criteria, but the domain is specific enough that an agent can infer appropriate use.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the return-content scope (biography, board seats, compensation, share trades), which is useful, but it does not disclose additional behavioral traits such as error behavior or data freshness. 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 a single, front-loaded sentence that states the action, the resource, the lookup key, and the main content categories. There is no filler, redundancy, or unnecessary caveat.

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

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

For a simple two-parameter read-only tool with a full output schema and rich annotations, the description supplies everything an agent needs to invoke it correctly: the resource type, the identifier mechanism, and the scope of returned data. Missing items like explicit alternatives are not required 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%, so the schema already documents both parameters and the slug example. The description only repeats the slug concept and lists returned fields, which maps loosely to the include parameter but adds little beyond the schema. A 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 opens with a specific verb and resource: 'Get detailed profile for a specific director by slug.' It clearly distinguishes this singular detail endpoint from the plural listing tool get_directors and other director-related siblings by emphasizing the slug-based lookup and the included content areas (biography, board seats, compensation, share trades).

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: use this when you have a director slug and need a detailed single-director profile. However, it does not explicitly state when not to use it or name alternatives such as get_directors for listing directors. This is adequate but relies on 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return-field and filtering context, but no additional behavioral traits such as pagination behavior, matching semantics, or response limitations beyond the 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?

Two short sentences deliver the core purpose, return contents, and operational modes with no filler. The most important information is front-loaded, making it easy for an agent to parse quickly.

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, optional-parameter search tool with an output schema and comprehensive annotations, the description covers the essentials: what it searches, what it returns, and how to filter. It could add a pointer to get_director_detail for cases requiring single-director depth, but that is a minor gap rather than a blocking omission.

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 limit, search, company, and current. The description's mention of filtering by company or searching by name mirrors the schema rather than adding new semantic detail, keeping this 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?

The description opens with a specific verb and resource: 'Search NZX company directors,' and lists concrete return fields (name, bio, board seats). It is clear on function but does not explicitly differentiate itself from the sibling get_director_detail beyond implying a list/search focus.

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?

'Filter by company or search by name' communicates the two primary usage modes, so when to use the tool is implied. However, it does not explicitly state when not to use it or mention get_director_detail as the alternative for individual director information, leaving some 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 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 read-only, idempotent, and non-destructive behavior, so the description does not need to restate safety. It adds useful dataset context such as record counts and coverage categories, but does not disclose additional behavioral traits like default year behavior, pagination, or result shape.

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: the first identifies the operation and scope, the second itemizes included data categories. The record counts add useful context even if not strictly necessary, and the text remains compact and scannable.

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

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

For a simple two-parameter read-only tool with a full output schema and complete parameter descriptions, the definition is sufficient for correct tool selection. It does not explain optional-year semantics, but that is not critical given the schema and annotations.

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?

Both parameters are already described in the schema with 100% coverage, so the schema carries the parameter meaning. The description adds no detail about ticker format, year ranges, or how the optional year behaves, providing no parameter-level value beyond the schema.

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

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

States a specific action and resource: retrieving ESG data for an NZX company. The description enumerates emissions, diversity, safety, and reporting standards, which clearly distinguishes it from overlapping sibling getters like get_governance_scores or get_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 gives implied context: this is the tool for ESG data for NZX issuers. However, it does not explicitly state when to choose it over overlapping siblings or provide exclusion criteria, leaving alternative selection 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 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no additional behavioral traits such as default time windows, date semantics, or result ordering. There is no contradiction between the description and 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 a single, focused sentence that front-loads the action and resource. Every phrase contributes meaning, with no filler or repetition of annotation data.

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 annotation, fully described optional parameters, and the presence of an output schema, the description is sufficient for an agent to call this tool correctly. It could have added a note about default behavior when 'days' is omitted, but nothing critical 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 all four parameters are already documented in the schema. The description mentions output fields like amounts and dates but does not add parameter-level guidance beyond what the schema provides. 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 names a specific verb ('Get'), a specific resource ('director share transactions (insider trades)'), and a market scope ('NZX companies'). It also conveys the key data dimensions (who is buying/selling, amounts, dates), which clearly separates it from siblings like get_board_changes or get_directors.

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 by describing what it returns, but it gives no explicit usage context, exclusions, or contrast with related siblings such as get_substantial_holders. It is clear enough for a straightforward read-only query, but leaves selection reasoning 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, 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description does not need to repeat safety. It adds useful behavioral context beyond annotations by noting that profile data is included only 'where linked to shared.people' and providing coverage stats (127 issuers). This gives agents a better expectation of data availability and sourcing without contradicting any annotation.

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 wasted words. It front-loads the primary purpose, then details the returned data, then adds coverage and filter info. Each sentence earns its place, and the structure is clean and scannable for an agent.

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 (return format is specified elsewhere) and only two simple parameters, the description covers everything an agent needs: what the tool does, what data it returns, how many issuers are covered, and how to filter by role. It even notes conditional profile linking. There are no significant gaps for a read-only, idempotent lookup tool.

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

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

Schema description coverage is 100%: both parameters (ticker and role) are fully documented with descriptions, and role includes a list of normalized values. The description's mention of 'Filter by role' adds no new meaning beyond the schema's role parameter description. Per the rubric, a baseline of 3 is appropriate when the schema already carries the parameter semantics.

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

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

The description states a specific verb and resource: 'Get the management team (C-suite executives) for an NZX company.' It enumerates the returned data (roles, tenure, biographies, education, profile links) and provides coverage metrics (127 issuers, 508 executives). This clearly distinguishes it from sibling tools like get_directors or get_board_changes, so an agent can select it correctly without ambiguity.

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 clear context that this tool is for C-suite executives and mentions filtering by role, but it does not explicitly state when not to use it or name alternative tools. The sibling list implies alternatives (e.g., get_directors for board members), but no direct exclusions or comparisons are made. Thus it meets the 'clear context, no exclusions' 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 already declare readOnly/idempotent/non-destructive, so the bar for added behavioral context is lower. The description adds meaningful behavior: it returns a unified cross-market stream, can combine multiple signal types, and includes composite signals that detect patterns like insider selling plus earnings miss. It also clarifies the feed's broad scope, which is not inferable from the schema alone.

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

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

The description is front-loaded with the core definition and scope, then gives compact example queries and routing. It is longer than average, but the length is justified by the large palette of signal types and the need to distinguish siblings. The final caution about routing is somewhat redundant with the earlier routing statement but earns its place by preventing misuse.

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 six-parameter, no-required-parameter tool with an output schema, the description plus schema covers what an agent needs: purpose, scope, routing, parameter semantics, and return coverage via the output schema. It explicitly handles the common confusion with sibling tools and provides example invocations. No critical behavior or parameter concern is left 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% and each parameter (days, type, limit, sector, ticker, significance) already has a semantic description with defaults and examples. The tool description doesn't need to repeat parameter details, so the baseline of 3 applies. It does reinforce the available signal type vocabulary informally, but the schema already lists the exact underscore codes.

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 the Market Intelligence Feed') and immediately defines its scope as a unified stream of all NZX market events. It differentiates itself from sibling tools by explicitly stating it is the cross-market feed and by naming the specific single-dataset tools it is not. The enumeration of 13 signal types leaves no ambiguity about what the tool covers.

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

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

Contains explicit routing guidance: use it for 'what is happening across the market' or when scanning several signal types at once, and avoid it for a question about one dataset for one company. It names the preferred sibling tools for single-dataset queries (get_capital_raises, get_agm_resolutions, etc.) and adds the warning that listing a signal type does not mean this is the best tool. Example phrasings ('what happened on the NZX today/this week?') anchor when to use it.

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

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

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, so the safety profile is covered. The description adds meaningful behavioral context: multi-year history (2010-2026), record counts, HHI index, holder types, YoY changes, and substantial-holder voting percentages. It also explains historical-data usage via year/all parameters.

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

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

The description is compact, front-loaded with the core purpose, and uses three sentences to cover resource, data scope, output dimensions, and usage hint. Every sentence adds value; the statistics are extra but not distracting.

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 mostly sufficient. It explains data scope, history, and metrics, but the unsupported 'all=true' parameter creates a correctness gap. The overlap with get_substantial_holders is also not resolved, which could lead an agent to select the wrong 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 coverage is 100%, so the schema already documents ticker and year. The description adds a useful year example, but it also introduces '?all=true', a parameter that is absent from the input schema while additionalProperties is false. This is misleading: an agent following the description may try to pass an unsupported 'all' argument.

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 verb and resource: 'Get top 20 shareholders and substantial holders (5%+) for an NZX company.' It also adds useful specificity about HHI, holder types, and YoY changes. However, it does not distinguish this tool from the sibling get_substantial_holders, which overlaps by name and by the substantial-holders portion of the description.

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 intended usage is implied by the first sentence, and the description gives invocation examples like 'Use ?year=2025 or ?all=true'. However, there is no explicit guidance about when to choose this tool over alternatives—particularly get_substantial_holders—and no exclusions or when-not-to-use 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 clear. The description adds valuable behavioral context: approximate dataset size (~267 records across ~85 issuers), the types of fields returned, and the fact that this is legally mandated disclosure data. No contradictions 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 appropriately sized and front-loaded with the core purpose, followed by data contents, use cases, and a comparison with the sibling tool. Every sentence adds value, though it could be slightly tightened without losing meaning.

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 an output schema, the description is complete: it explains the data source, coverage, fields, use cases, and relationship to get_shareholders. The annotations cover idempotency and safety, and the schema covers both parameters, so nothing essential is missing for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and both parameters are already described in the schema: ticker is an NZX ticker symbol, and include_ceased toggles former substantial holders. The description adds some related context about threshold crossing history but does not materially expand on parameter semantics 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?

The description states a specific verb ('Get'), a clear resource (substantial shareholders for an NZX company), and precise scope (5%+ voting rights from NZX disclosure notices). It also distinguishes itself from the closely related get_shareholders by noting the difference between legally mandated real-time disclosures and top-20 annual report 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 provides explicit use cases (block holder analysis, activist investor tracking, M&A signal detection, ownership concentration analysis) and names get_shareholders as a complementary alternative. It clearly positions this tool as the real-time disclosure source versus annual report data, though it does not state an explicit 'when not to use' condition.

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 declare this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral details beyond these hints: it performs AI-based extraction of summary, sentiment, entities, and risk flags, and it may return cached results. 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?

Three sentences with no filler. The purpose is front-loaded, followed by the key behavioral details (AI extraction, cache behavior) and parameter sourcing. 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 single-parameter read-only tool with a rich output schema, the description covers what the tool does, how to obtain the required input, and the main behavioral nuance (caching). Nothing material is missing 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 coverage is 100% and the schema already documents the announcement_id parameter. The description adds value by specifying the source of the ID (search_announcements results) and providing a concrete example ('12345'), which helps the agent supply a correctly scoped value.

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-resource pair ('Read and analyze a specific NZX announcement') and clearly distinguishes this from the sibling search_announcements tool by focusing on analysis of a single existing announcement. The listed outputs (summary, key figures, sentiment, entities, risk flags) make the tool's purpose unambiguous.

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

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

The description explicitly instructs the agent to obtain the announcement_id from search_announcements results, which establishes the intended workflow and dependency. It does not explicitly state when not to use this tool versus the sibling get_* tools, but the guidance is clear enough for 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?

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns a list with sector and market cap and emphasizes it is not an answer-producing tool. It does not mention pagination or limit behavior, but given the annotation coverage, the added routing context justifies a 4.

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 concise sentences plus a clear ROUTING directive. It front-loads the purpose and then gives actionable routing. No wasted words; 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?

Given the tool has only 3 optional parameters, an output schema, and annotations covering read-only/idempotent behavior, the description fully covers what an agent needs: how to use it, what it returns, and how to proceed after searching. The routing guidance is especially valuable given the large sibling set.

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% — every parameter (limit, search, sector) has a description. The tool description does not add extra parameter-level meaning; it only restates search by name or ticker, which is already in the schema. Baseline of 3 is appropriate since schema handles parameter documentation.

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 ('Search') and resource ('NZX-listed companies') with clear scope (by name or ticker) and output (list with sector, market cap). It distinguishes itself from the many get_* siblings by framing itself as the lookup step.

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 instructs when to use: 'Use this to find a company ticker before calling other tools.' Provides routing: 'a lookup step, not an answer' and names specific alternatives (get_credit_ratings, get_executive_compensation) plus the warning 'Do not stop after searching.' No ambiguity about how it fits among siblings.

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