nzxplorer-mcp

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

No annotations are provided, so the description carries full burden. It correctly implies a read operation but does not disclose potential error conditions, data availability constraints, or any side effects. The behavioral transparency is adequate but not thorough.

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, front-loading the action and resource in the first sentence, and providing details and use case in the second. No extraneous words.

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 simplicity (2 parameters, no output schema), the description covers the purpose, output fields, and use case. It lacks details on output structure or error handling, but is sufficiently complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond the schema for the parameters (ticker and year). It mentions the output but not parameter-specific details.

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 gets AGM resolution voting data for NZX companies, listing specific data points (resolutions, votes, pass/fail status, support percentages). It is a specific verb-resource combination that distinguishes it from sibling tools like get_dividends or 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 provides a clear use case ('governance and shareholder activism analysis'), but does not explicitly state when not to use it or name alternative tools. The context is sufficient for guided usage, but lacks explicit exclusions.

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?

No annotations are provided, so the description carries full burden. It states what the tool shows (URLs, financial year, status) but does not disclose behavioral traits like read-only nature, authentication needs, or rate limits. Basic transparency is present but lacks depth.

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 redundant words. It efficiently conveys purpose, output, and usage guidance.

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 tool with three parameters and no output schema, the description gives a reasonable overview of what is returned (URLs, financial year, status). It could be more complete by describing whether multiple reports are returned or the structure of the response, but it is sufficient for most uses.

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 adds context about the output but does not enhance parameter meaning 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 clearly states the tool retrieves annual and interim report URLs for NZX companies, specifying the resource and output fields (report URLs, financial year, extraction status). It distinguishes from siblings like get_financials and get_earnings by focusing on report links.

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 says to use this tool when asked about annual reports, filings, or report history. It provides clear context but does not mention when not to use it or suggest alternative tools for related but distinct queries.

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?

No annotations are provided, so the description carries full burden. It mentions events, dates, and reasons, indicating a read operation, but does not explicitly state it is read-only, nor does it disclose authentication needs, rate limits, or behavior when no changes are found.

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, concise and front-loaded with the action and resource. No unnecessary words or details.

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

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

Given the tool has 5 parameters but no output schema, the description explains the nature of the returned data (events with dates and reasons). It covers the main purpose but could mention ordering or pagination behavior. Almost complete for a list 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% (all 5 parameters have descriptions). The description adds context about output but does not explain parameter semantics beyond what the schema provides. 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 clearly states the verb 'Get' and the resource 'director appointment, resignation, and retirement events', specifying the scope ('for an NZX company') and the output ('board composition changes over time with dates and reasons'). This distinguishes it from sibling tools like get_directors or get_director_detail.

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 but does not explicitly state when to use this tool versus alternatives (e.g., get_directors for current directors) or when not to use it. No exclusions or context provided.

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

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

No annotations are provided, so the description must disclose behavioral traits. It implies a read-only operation ('get') and provides data coverage (11,700 events, 131 issuers), but it does not mention authentication, rate limits, or potential side effects. The description is moderately transparent but lacks full behavioral disclosure.

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 wasted words. The first sentence states the action and subject, the second adds scope, specificity, and data magnitude. 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?

No output schema exists, so the description should clarify return structure. It mentions included fields (amounts, pricing, dilution) and gives scale, which is helpful. However, it lacks explicit field names or an example structure, so it's not fully complete, but adequate for an API with good schema descriptions.

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

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

The input schema has 100% coverage with descriptions, but the tool description adds value by listing example raise types (placements, rights issues, etc.) that correspond to the 'type' parameter, and mentioning amounts, pricing, and dilution, which enrich understanding beyond schema alone.

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 it retrieves capital raise history for NZX companies, listing specific raise types and data points (amounts, pricing, dilution). It is distinct from sibling tools which focus on other financial 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?

No explicit when-to-use or alternatives are provided, but the tool's purpose is specific and self-explanatory. The description does not include exclusions, but it's clear from context that it is for capital raises, not other corporate actions.

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?

No annotations are provided, so the description must carry behavioral transparency. It lists what can be included but does not disclose response format, potential API calls, performance implications, or whether all includes are always available.

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?

A single, efficient sentence that clearly communicates the tool's purpose and capabilities without verbosity.

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 simplicity (2 params, no nested objects) and the absence of an output schema, the description is adequate but could mention that the response is a consolidated report and that some includes may be missing for certain companies.

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 description adds minimal value beyond the schema. It restates the include options and provides ticker examples, which are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves detailed info for a specific NZX company by ticker, listing possible data categories (directors, financials, governance score, stock price). This distinguishes it from sibling tools that focus on individual aspects.

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 use when a broad overview of a company is needed, and the sibling tools provide more specific data. However, it does not explicitly state when not to use this tool (e.g., for simpler queries).

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?

No annotations are provided, so the description must fully convey behavioral traits. It mentions that only ~20 NZX companies have ratings, which is useful, but it does not disclose whether the operation is read-only, any authentication needs, rate limits, pagination behavior, or how dates are handled. Given no annotations, this is insufficient.

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 extremely concise with only two sentences. It is front-loaded with the core purpose and adds essential context without any waste. Every sentence serves a purpose.

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

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

Given no output schema, the description provides sufficient context about the tool's primary function: history of rating changes. It mentions the limited coverage (~20 companies), which helps set expectations. However, it lacks details on output format or historical depth, but for a simple retrieval tool this is acceptable.

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 baseline is 3. The description adds little beyond the schema: it mentions agencies and actions, but the schema already enumerates them. No additional details on parameter usage or constraints are provided.

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

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

The description clearly states the tool retrieves credit rating history for NZX companies, specifies the agencies (S&P, Moody's, Fitch, AM Best) and types of changes (upgrades, downgrades, outlook changes), and notes the limited scope (~20 NZX companies). This clearly distinguishes it from sibling tools that focus on other financial 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?

No explicit guidance is provided on when to use this tool versus alternatives. While the context of sibling tools implies it is for credit ratings specifically, there is no mention of when not to use it or when other tools (e.g., get_financials) would be more appropriate.

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 details the content returned but does not disclose whether the tool is read-only, any authentication requirements, rate limits, or data recency. Since annotations are absent, more behavioral context would improve transparency.

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, front-loads the purpose, and contains no fluff. Every sentence adds value, making it concise 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?

The description lists several return components but does not specify their structure or format. With no output schema, more detail on the return format would improve completeness. Still, it covers the main areas adequately.

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 fully describes the single parameter 'days' with range and default. The tool description does not mention or elaborate on it, so it adds no extra meaning beyond the schema. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states it returns a daily NZX market wrap covering all active issuers, listing specific data points like price moves, market breadth, and announcements. This differentiates it from sibling tools that focus on individual company 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 explicitly states 'Use when asked about overall market conditions, today's market, what happened on the NZX, or market summary,' providing clear use cases. However, it does not explicitly mention when not to use it or name alternative sibling tools.

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?

No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, idempotency, or potential effects. It only lists included data sections without further context.

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

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

The description is concise (two sentences), front-loaded with the main action and key details, with no redundant or unnecessary 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 tool has two parameters and no output schema, the description adequately explains the tool's output content. However, it could be slightly more complete with a note about the return format or structure.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds no additional semantic value beyond what the schema provides, meeting 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 clearly states the tool retrieves a detailed profile for a specific director identified by slug, and lists key content areas (biography, board seats, compensation, share trades). This differentiates it from sibling tools like 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 usage for obtaining a single director's detailed info by slug, but does not explicitly mention when to use alternatives like get_insider_trades for trades or get_management_team for team members.

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?

With no annotations, description carries full burden. It lists return fields but fails to disclose behavioral traits like read-only nature, pagination behavior, or what happens when no results match. The description is minimal on behavioral context.

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

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

Two sentences efficiently convey purpose, return, and usage hints. Front-loaded with key intent. No redundancy, 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?

Given 4 optional parameters, no output schema, and no annotations, the description is incomplete. It omits the 'current' boolean parameter (which defaults to true) and the 'limit' parameter, leaving significant behavioral and usage gaps for a search 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 covers all parameters with descriptions, so baseline is 3. Description reinforces the purpose of 'company' and 'search' parameters but adds no new semantic detail beyond the schema. The 'current' and 'limit' parameters are not mentioned in the description.

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 clearly states the verb 'Search' and resource 'NZX company directors', and specifies return fields (name, bio, board seats). It distinguishes from sibling tools like get_director_detail by implying a search 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?

Hints at filtering by company or searching by name, which provides basic usage context. However, no explicit guidance on when to use this tool vs. alternatives (e.g., get_director_detail), nor exclusions or prerequisites.

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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does not mention authentication requirements, rate limits, destructive actions, or whether the tool is read-only. The description only lists returned data, omitting operational behavior.

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

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

The description is concise: two sentences with the core purpose first. It avoids redundancy but could be slightly more structured (e.g., separating input from output). Overall, it earns its space.

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

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

Given no output schema and the tool's richness (dividend history with multiple fields, safety score, etc.), the description adequately explains the return data. However, it lacks details on pagination, date range limits, or error cases, preventing a perfect score.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description adds context about the output but does not elaborate on parameter usage beyond what the schema provides (e.g., date range format). Baseline 3 is appropriate as the schema already documents parameters.

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

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

The description clearly states 'Get dividend history for an NZX company' and enumerates specific data fields (ex-date, payment date, amount, etc.), making the tool's purpose 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?

The description implies usage for dividend history queries but does not explicitly state when to prefer this tool over alternatives, nor does it mention prerequisites or limitations. The mention of 'Company pages also show...' is additional detail, not usage 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?

No annotations provided, so the description must carry the burden. It states data is extracted from announcements, but does not disclose whether it is read-only, authorization needs, rate limits, or data freshness. The behavioral traits are under-specified.

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 core purpose. No redundant 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?

Does not explain return format, pagination behavior of 'limit', or how to handle different periods. Lacks details needed for effective use without trial and error.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description does not add meaning beyond the schema, only mentioning output fields. 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 states the verb 'Get', resource 'earnings results for an NZX company', and source 'full-year and half-year announcements'. It lists specific metrics, distinguishing itself from siblings like get_financials or get_revenue_segments.

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 versus alternatives like get_financials or when to choose a period parameter. It does not specify limitations or prerequisites.

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 discloses detailed data categories and record counts, providing transparency beyond the schema. However, it does not explicitly state that the tool is read-only or mention any side effects, despite the absence of 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 paragraph with three sentences, front-loading the purpose and efficiently listing data categories. Could be more structured with bullet points, but it is concise and informative.

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

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

The description adequately covers what data is retrieved but does not describe the output format or structure. Without an output schema, the missing information about response shape limits completeness.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add additional meaning beyond the schema, such as expected date format for 'year'. Baseline score 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 states the tool retrieves ESG data for an NZX company and enumerates specific categories (emissions, diversity, safety, reporting standards), distinguishing it from sibling tools like get_governance_scores.

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 versus alternatives. The description lists data contents but does not explain scenarios where this tool is preferred over similar tools like get_governance_scores or get_directors.

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?

No annotations provided, so description must disclose behavioral traits. It mentions filtering but doesn't clarify read-only nature, rate limits, data freshness, or error handling. Minimal behavioral context beyond the obvious.

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 that front-load the purpose and immediately mention included data types. No redundant 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 no output schema and no annotations, the description lacks details on return format, pagination behavior of the limit parameter, and prerequisites. It is incomplete for an agent to fully understand the tool's behavior.

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

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

Schema coverage is 100% with descriptions for each parameter. The description reiterates filtering by statement type and year but adds little beyond schema. The mention of 'financial ratios' aligns with the 'ratios' statement type, providing slight additional context.

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 clearly states the tool retrieves financial statements for NZX companies, lists included statement types (income, balance, cash flow, ratios), and mentions filtering. This distinguishes it from many sibling tools like get_earnings 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?

No explicit guidance on when to use this tool vs siblings or when not to. The description implies usage for financial statement retrieval but doesn't mention alternatives or exclusions, leaving the agent to infer.

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?

No annotations are provided, so the description carries the full burden. It discloses the scale and components but does not mention behaviors like default sorting, result limits, or read-only nature. More behavioral details would enhance transparency.

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, front-loaded with the primary purpose followed by details. Every sentence adds value 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?

Given 7 parameters and no output schema, the description explains the score scale and components but omits return format, pagination, or default behavior. It is largely complete but could benefit from return structure hints.

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 description adds little beyond the schema. It mentions filtering by sector, rating, or score range, aligning with parameters but not providing additional semantics or format details.

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 retrieves Governance Risk Scores for NZX companies, explains the 0-100 scale and six components, and lists filtering options. It distinguishes itself from sibling tools by specifying the unique domain of governance scoring.

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 mentions filtering capabilities but does not explicitly state when to use this tool vs. alternatives. However, given the diverse sibling tools, the context implies this is for governance scores, making usage 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?

With no annotations provided, the description carries full burden for behavioral traits. It does not disclose side effects, authentication needs, rate limits, or behavior when no results are found. The description only states output contents without operational context.

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

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

The description is brief and direct, with two sentences conveying purpose and output. No wasted words, but lacks structural elements like bullet points that could improve scanability.

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

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

Given no output schema and 4 optional parameters, the description is insufficient. It omits response format, pagination details, default behaviors, and examples. More context is needed to cover what the tool returns and how parameters affect results.

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 baseline is 3. The description adds no additional meaning beyond schema descriptions for parameters (days, type, limit, ticker). It does not explain interactions or constraints not already in schema.

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

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

The description clearly states the tool retrieves director share transactions (insider trades) for NZX companies, explicitly mentioning what data is shown (who, amounts, dates). It distinguishes itself from sibling tools like get_director_detail and get_directors, which focus on director profiles rather than 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?

No guidance on when to use this tool versus alternatives, no prerequisites, no context on filtering behavior beyond implicit parameter uses. Lack of when-not-to-use instructions or sibling differentiation limits utility.

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 discloses the date range (Dec 2018 - Sep 2022), which is a key behavioral trait. However, with no annotations, the description lacks disclosure of auth needs, rate limits, or behavior for invalid inputs or empty results.

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, front-loaded with the key action, and contains no fluff. It could be slightly more structured but is appropriately concise.

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

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

Given no output schema, the description explains the return values (funds, market value, percentage). It covers the data range. For a low-complexity tool, this provides adequate completeness, though it lacks details on optional date behavior.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions the date range but does not explicitly tie it to the date parameter or add significant meaning beyond the schema's existing descriptions.

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 action ('Get') and the specific resource ('KiwiSaver fund holdings in an NZX company'). It details what data is shown and the date range, making the purpose unambiguous and distinct from sibling tools like get_shareholders.

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 versus alternatives such as get_shareholders or other holdings-related tools. The description does not specify prerequisites, limitations, or comparisons with siblings.

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?

With no annotations, the description carries full burden. It describes return data (roles, biographies, etc.) and coverage, but does not explicitly state the operation is read-only or disclose potential constraints like rate limits. The description is adequate but not comprehensive.

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, well-structured paragraph. The first sentence clearly states the purpose, and subsequent sentences add details without redundancy. Every sentence serves a purpose.

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 retrieval tool with two parameters and no output schema, the description is remarkably complete. It covers what it returns, coverage stats, filtering option, and data sources. No critical information is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the role filter with examples and mentioning that profile data is included where linked, which goes beyond schema descriptions.

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 gets the management team (C-suite executives) for an NZX company, specifying the verb, resource, and scope. It distinguishes from sibling tools like get_directors by focusing on executives rather than the board.

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 context for using the tool (e.g., filter by role) but lacks explicit guidance on when not to use it or mentions of alternative tools. Since no exclusions or alternatives are stated, the score is moderate.

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?

No annotations are provided, so the description carries full burden for behavioral disclosure. It lists what signal types are returned but does not mention whether the operation is read-only, rate limits, authentication needs, pagination behavior, or data freshness. The description 'Returns 13 signal types' is informative but lacks critical operational context.

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

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

The description is front-loaded with the core purpose, then lists signal types, and ends with usage examples. It is moderately sized for the complexity (6 params, 13 types) and avoids filler. However, it could be slightly more concise by removing the comma-separated list of signal types from the second sentence.

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 complexity (6 parameters, many sibling tools, no output schema), the description covers the tool's scope well. It explains what data is returned (13 signal types) and gives concrete queries. It lacks details on return format (e.g., fields per signal) but remains complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, but the description adds value beyond schema by specifying default values (e.g., days default 180, use 7 for 'this week') and enumerating signal types. This helps agents map natural language requests to parameter values.

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 gets a unified stream of all NZX market events, listing 13 specific signal types. It distinguishes itself from sibling tools that focus on individual signal types (e.g., get_insider_trades, get_dividends) by offering an aggregate view.

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 example queries (e.g., 'what happened on the NZX today/this week?', 'any recent insider trades?') that directly guide when to use the tool. It implicitly suggests alternatives via the sibling tools but does not explicitly exclude use cases like 'for a single signal type, use the dedicated tool instead'.

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?

No annotations are provided, so the description carries full burden for behavioral disclosure. It only states what data is returned but omits any behavioral traits such as data source, update frequency, response format, pagination, or rate limits. A mutation tool with zero annotations should describe these aspects.

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, front-loading the main action and scope. The second sentence efficiently lists ratio groups and usage. No extraneous words.

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

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

Given no output schema and no annotations, the description should provide more about the expected output format or behavior. It does not describe how results are returned (e.g., list of ratios with values), any constraints like date range limitations, or how to interpret the composite metric. It is adequate for basic understanding but lacks completeness for operational 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 baseline is 3. The description adds value by naming ratio categories and specific examples (comprehensive_roe, oci_divergence, paid_in_capital_ratio, share_capital_growth), which are not in the parameter descriptions. This helps users understand what metrics can be sorted or filtered.

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 it retrieves financial metrics/ratios for NZX companies, listing 46 ratios across categories like profitability, leverage, cash flow, dividends, growth, valuation, and composite. This specific verb and resource sets it apart from sibling tools that retrieve different data types.

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 says 'Use for screening or comparison,' indicating its purpose. While it does not mention when not to use or directly compare to alternatives, the sibling tools are distinct enough (e.g., get_dividends, get_stock_prices) that the context is 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?

No annotations provided, so description carries burden. It implies a read-only operation but doesn't explicitly state that or disclose any side effects, rate limits, or auth requirements. The listed return fields provide some behavioral insight.

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: first states purpose and returns, second gives usage. No redundancy, 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?

Adequately covers purpose, inputs, and outputs for a simple tool. Could mention that returns include multiple timeframes without further specification, but output is clear enough.

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

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

Schema coverage is 100% with a single parameter (ticker). Description adds no additional meaning beyond the schema; 'NZX company' aligns with schema's 'NZX ticker symbol'.

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 clearly states verb ('get'), resource ('stock performance metrics'), and scope ('NZX company'). It lists specific return fields (1d to 5y, alpha, volatility, etc.), distinguishing it from sibling tools like get_stock_prices 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?

Explicitly states use case ('performance comparison and pay-for-performance analysis'). Lacks explicit when-not or alternatives, but context is clear given siblings.

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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It discloses that data is in NZD thousands and includes segment revenue, profit, and assets. However, it does not mention error handling for invalid tickers, data availability, or idempotency, which would be helpful for a read 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 two sentences with no extraneous information. The first sentence states the core purpose, and the second enumerates relevant search terms. Every word 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?

Given no output schema, the description provides sufficient insight into return contents (segment revenue, operating profit, assets in NZD thousands). However, it does not specify the exact structure (e.g., list of objects) or what happens when no segments are found. A minor gap for a moderately complex 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%, meaning all parameters are described in the schema. The description adds value by providing examples for ticker (e.g., "FPH", "SKC"), clarifying that 'type' filters by segment type, 'year' can be a range, and 'limit' caps results. This goes beyond schema descriptions.

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 retrieves revenue segment breakdown for an NZX company, specifying the types of segments (operating, geographic, product) and the data returned (segment revenue, operating profit, assets in NZD thousands). This distinguishes it from sibling tools like get_financials or get_earnings, which cover broader financial 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 explicitly lists trigger keywords ("revenue breakdown", "business segments", etc.) that signal appropriate use. It does not provide explicit when-not-to-use guidance or name alternative tools, but the trigger list effectively communicates context.

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?

Given no annotations, the description fairly discloses the data returned: ownership concentration, holder types, year-over-year changes, and voting rights. It also mentions the time range (2010-2026) and data sources. Missing details on error handling or rate limits.

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 informative and front-loaded with the main purpose, but slightly verbose. Every sentence contributes useful detail, though it could be tightened.

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 list tool with two parameters and no output schema, the description covers data content, time range, and parameter usage adequately. Lacks details on error responses or output format, but sufficient for typical selection.

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

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

Schema coverage is 100%, and the description adds value by interpreting the year parameter as fiscal year filtering and showing example usage (?year=2025, ?all=true), which goes beyond the schema alone.

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 retrieves top 20 shareholders and substantial holders for NZX companies, with specific verb and resource. However, it does not distinguish from the sibling tool 'get_substantial_holders', which likely overlaps in functionality.

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 usage examples for the year parameter and indicates optional 'all=true' for historical data, but does not explicitly state when to prefer this tool over alternatives like 'get_substantial_holders'.

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?

No annotations are provided, so the description must convey all behavioral traits. It states the tool is read-only and provides daily OHLCV data, but does not disclose authentication requirements, rate limits, or how invalid tickers are handled. Missing return format details.

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, concise sentence with no wasted words. It is front-loaded with the core action and context.

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

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

Given no output schema, the description omits the return format (e.g., array of objects with fields). It implies OHLCV but does not confirm structure. It adequately covers purpose and parameters but lacks output details.

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?

All four parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds value by explaining the data type (OHLCV) and market (NZX) but does not elaborate further on parameter syntax or formats.

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 retrieves daily stock price history (OHLCV) for NZX companies, with a specific verb 'Get' and resource. It also indicates usage for price trends and returns, distinguishing it from sibling tools like '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 provides clear usage context: 'Use for price trends, returns, and technical context.' It implies when to use but does not explicitly mention when not to use or list alternatives, though the purpose is well-scoped.

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?

No annotations provided; description covers key behavioral traits: source (NZX disclosure notices), approximate record count (267 across 85 issuers), and data fields. Lacks details on idempotency, rate limits, or authorization, but adequate for a read-only data retrieval tool.

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?

Well-structured, front-loaded with purpose. Each sentence adds value: purpose, scale, content, use cases, sibling contrast. No wasted words.

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 2 parameters and no output schema, description covers inputs, outputs (fields), use cases, and differentiation. Could mention whether data is paginated or historical coverage, but overall sufficiently complete for a simple data retrieval 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 description adds minimal value beyond schema. ticker and include_ceased are described adequately in schema; description does not provide new semantics, only contextualizes include_ceased as 'former substantial holders who dropped below 5%'.

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?

Clearly states the tool retrieves substantial shareholders (5%+ voting rights) for NZX companies from disclosure notices, listing specific data fields. Differentiates from sibling get_shareholders by mentioning it complements top-20 annual report data with real-time disclosures.

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 lists use cases: block holder analysis, activist tracking, M&A signal detection, ownership concentration analysis. Provides clear differentiation from get_shareholders, guiding when to use this tool over alternatives.

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?

No annotations exist, but the description lists returned fields (acquirer, target, offer price, etc.) and covered deal types. It does not describe side effects, but as a getter tool, this is sufficient. Adds value beyond 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 sentences: first states core purpose, second details return structure and use cues. No fluff, 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?

With 5 parameters and no output schema, the description thoroughly explains return fields and covers all parameter types. Complete for an info-retrieval 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 baseline is 3. The description mentions 'year or range' and lists deal types, but the schema already documents all parameters. Minimal additional 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?

Clearly states 'Get M&A and takeover activity for an NZX company.' Distinguishes from siblings by listing specific deal types and associated queries. No other tool targets this niche.

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 query keywords like 'takeovers', 'M&A', 'acquisitions', and 'hostile bids'. Does not mention alternatives explicitly, but the keywords sufficiently guide when to 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?

No annotations provided, and the description does not disclose any behavioral traits (e.g., read-only nature, data freshness, rate limits). It implicitly describes a read operation but lacks explicit behavioral disclosure.

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, no wasted words. First sentence states the purpose, second lists indicators and usage. Front-loaded and efficient.

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

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

Lacks output schema, and the description does not specify the return format (e.g., JSON). However, it lists the indicators, giving the agent a good idea of what to expect. Could be improved by mentioning the response structure.

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 only parameter (ticker), and the schema already provides a good description. The description does not add extra meaning 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?

Clearly states it retrieves technical analysis indicators for NZX companies, listing specific indicators (SMA, RSI, etc.). Distinguishes from siblings like get_market_signals by being explicitly for NZX 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?

Provides clear context: 'Use for trading signals, momentum analysis, and technical screening.' Does not explicitly exclude alternative tools, but the usage guidance 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?

No annotations provided, so description carries full burden. It mentions caching behavior and AI usage, which are important. However, it does not explicitly state non-destructiveness or error handling for invalid IDs. With annotations missing, more detail would be beneficial.

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, no redundancy, front-loaded with main purpose. Each sentence provides essential information: what it does, how to use it, and caching behavior.

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 one parameter and no output schema, description covers input source and list of extracted fields. It lacks details on output structure, but the summary of extracted data compensates somewhat. Could mention error handling or rate limits, but overall complete for a simple 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?

Single parameter announcement_id with 100% schema coverage. Schema already describes it fully. Description adds example format ('12345') but no meaningful new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Read and analyze' and the resource 'NZX announcement', listing extracted fields (summary, key figures, sentiment, entities, risk flags). It is distinct from sibling tools like search_announcements which finds announcements.

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 requires the announcement_id from search_announcements results, providing an example format. It implies a workflow (search first, then analyze) but does not explicitly state when not to use or list alternatives.

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?

With no annotations provided, the description carries the full burden. It explains that the tool searches titles and full text, and lists possible AI-enriched result fields (ai_category, ai_summary, etc.). However, it does not disclose pagination behavior, the effect of leaving the query empty, authentication needs, or rate limits. Some behavioral aspects are left implicit.

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: it starts with the primary purpose, then details the scope and results. Every sentence provides useful information without repetition. It is slightly lengthy but appropriate for the tool's complexity.

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

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

Given no output schema and 6 parameters, the description covers the search functionality, result fields, and date range. It mentions that results may include AI fields like sentiment and risk flags. It does not explain the exact output structure beyond these fields, but for a search tool, it is reasonably complete.

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 documentation covers all 6 parameters with descriptions. The tool description adds value by emphasizing that the query searches both titles and document content, and by listing the AI fields that may appear. However, it does not provide additional per-parameter semantics beyond what the schema already states, so a 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 clearly states 'Full-text search across 64,000+ NZX market announcements' and specifies that it searches both titles and full document content. It effectively distinguishes itself from sibling tools that provide specific data types (e.g., dividends, earnings) or read single announcements.

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 says 'Use for finding mentions of specific topics, companies, people, or events across all NZX filings,' providing clear guidance on when to use this tool. It does not explicitly state when not to use it or mention alternatives, but the context of sibling tools implies that other tools are for specific data retrieval.

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?

No annotations are provided, so the description must carry the full burden. It mentions what is returned but lacks details on pagination, sorting, error handling, or any side effects. For a search tool, basic behavioral context like 'returns up to 10 results by default' would be helpful.

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 concise with two sentences: one for purpose and output, one for usage guidance. Every sentence adds value without 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?

Given the tool's simplicity (no required params, no output schema, no nested objects), the description adequately explains the core functionality and return values. It could mention case-insensitivity or default limit behavior, but it is sufficient for an agent to use 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% for all three parameters. The description adds no additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches NZX-listed companies by name or ticker and returns a list with sector and market cap. It uses a specific verb ('Search') and resource ('companies'), and distinguishes it from sibling tools which are for specific details like financials or announcements.

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 says 'Use this to find a company ticker before calling other tools,' providing clear guidance on when to use it. It implies a prerequisite role but doesn't explicitly list when not to use it or alternative tools.

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