nzxplorer-mcp

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

No annotations provided, so description carries full burden. Describes read-only data retrieval but does not disclose potential behavioral traits like pagination, rate limits, or whether missing year returns all years.

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, front-loaded sentences with no fluff. Every sentence adds value: first defines purpose, second lists deliverables.

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?

Adequate for a simple 2-parameter tool with no output schema. Lacks detail on behavior when year is omitted, but overall covers core purpose and data returned.

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. Description reinforces ticker's purpose but adds minimal extra value beyond 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?

Clearly states it gets AGM resolution voting data for NZX companies, listing specific data fields (resolutions, votes, status, percentages). Distinct from siblings which cover other company 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?

Provides use case ('governance and shareholder activism analysis') but lacks exclusions or comparison to sibling tools like get_governance_scores or get_company_detail.

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 discloses that the tool shows report URLs, financial year, and extraction status, confirming it is a read operation. However, it does not mention permissions, rate limits, or any side effects, which is adequate for a simple 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?

The description is two sentences long, front-loaded with the primary purpose and output, followed by usage guidance. Every sentence is efficient and adds value, with 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, the description adequately explains what the tool returns (URLs, financial year, status). Parameters are fully documented in the schema. It could mention ordering or pagination, but that is not critical for a straightforward 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%, meaning all three parameters have descriptions in the schema. The description does not add parameter-level detail beyond what the schema already provides, resulting in a baseline score of 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 clearly states the tool retrieves annual and interim report URLs for NZX companies, specifying the verb 'Get' and the resource 'annual and interim reports'. It lists the output attributes (URLs, financial year, extraction status), distinguishing it from sibling tools like get_financials or get_earnings.

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 when asked about a company's annual reports, filings, or report history,' providing clear guidance on when to use. It does not explicitly state when not to use, but the context implies alternatives exist for other financial data.

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 that results include 'dates and reasons,' but does not mention rate limits, data freshness, error handling, or what happens if the ticker is invalid. The tool is read-only, which is clear from the verb 'Get,' but transparency is basic.

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 wasted words. It front-loads the primary action ('Get director appointment...') and provides essential context about what the tool shows ('board composition changes over time with dates and reasons'). 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 the tool has 5 parameters, no output schema, and no annotations, the description is fairly complete. It explains the core purpose and the nature of results (dates and reasons). However, it could be more complete by mentioning pagination via the 'limit' parameter and explaining that events are listed chronologically. Still, it provides enough context for an AI agent.

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 context about 'board composition changes over time with dates and reasons,' which loosely aligns with date and action filters, but it does not add new meaning or clarify parameter usage 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 'Get director appointment, resignation, and retirement events for an NZX company,' specifying the verb ('Get'), resource ('board changes'), and scope ('NZX company'). It distinguishes from siblings like get_directors (current directors) and get_director_detail (individual details) by focusing on changes over time.

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

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

Usage context is implied: the tool is for board composition changes with date and action filters. However, it does not explicitly state when to use over alternatives (e.g., get_directors for current list) or provide exclusion criteria. The description lacks explicit guidance on when not to use this tool.

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

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

No annotations are provided, so the description must carry the burden. It reveals scalability (~11,700 events across 131 issuers) and that results include 'amounts, pricing, and dilution'. However, it does not explicitly state that the tool is read-only or mention any authentication needs, rate limits, or data freshness. This 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?

Two sentences front-load the purpose and quickly provide supportive detail (types, scale). Every word serves a purpose; 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?

Despite lacking an output schema, the description mentions included fields (amounts, pricing, dilution) and approximate event count, giving a good sense of the response. With 5 parameters fully covered by schema, the tool is nearly complete for a data retrieval tool. Minor gap: no explicit mention of sorting or pagination.

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 detailed descriptions for all parameters (ticker, type, year, limit, buybacks). The description adds context (enumeration of raise types, scale), but this largely overlaps with schema. The description provides no additional parameter semantics beyond what the schema already conveys, 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 the tool retrieves 'capital raise history' for an NZX company and enumerates specific types (placements, rights issues, SPPs, etc.), making the purpose very specific. It distinguishes itself from sibling tools (e.g., get_dividends, get_earnings) by focusing on capital events.

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 lists the types of capital raises included, which implies when to use it—for historical capital events. However, it does not explicitly state when not to use it or suggest alternatives among siblings (e.g., if only stock prices are needed). The context is clear but lacks 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 must fully disclose behavioral traits. It only states that the tool 'gets detailed info' and what can be included, but lacks details on authentication, rate limits, data freshness (e.g., 'latest stock price' is ambiguous), or error handling for missing tickers.

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 sentence that conveys the core purpose and capabilities without any fluff. It is appropriately sized and front-loaded with the main action.

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 is provided, so the description should compensate by describing the return structure. It does not mention the format or fields of the returned data, leaving the agent uncertain about what to expect. For a composite tool, this is a significant gap.

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 no extra meaning beyond what the schema already provides; it merely repeats the concept of includes. No new syntax or parameter relationships are explained.

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's purpose: gets detailed info for a specific NZX company by ticker. It lists the types of information that can be included (directors, financials, governance score, stock price), which distinguishes it from sibling tools that focus on single categories.

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 comprehensive overview via 'detailed info' and the list of includes, but it does not explicitly state when to use this tool versus the many sibling tools that offer each component individually. No when-not or alternative guidance is provided.

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

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

No annotations are provided, so the description carries full burden. It mentions that ~20 NZX companies have credit ratings, which is a useful limitation, and describes the data but does not disclose behavioral traits like response structure, rate limits, or side effects.

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

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

Two sentences, front-loaded with the main purpose, no unnecessary words. Highly 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?

Given the tool has no output schema and no annotations, the description provides adequate context: it specifies the scope (~20 companies), the types of ratings, and the changes tracked. Could mention response format but sufficient.

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 only marginal context beyond the schema (e.g., mentioning 'upgrades, downgrades, outlook changes'). This does not significantly improve 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 verb 'Get' and the resource 'credit rating history for an NZX company', listing agencies and types of changes, which distinguishes it from sibling tools that cover 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?

The description implies usage for obtaining credit rating history but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or context about 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 provided, so description fully handles transparency. It discloses that the tool returns a digest including price moves, market breadth, announcements, insider trades, dividends, board changes, and AI-generated content. Implicitly shows it is a read-only 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?

Single sentence with purpose upfront, followed by a list of contents. No redundant information. Could be slightly shorter but is 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?

Despite no output schema, description comprehensively lists all returned data categories (price moves, market breadth, announcements, etc.). This fully informs the agent of what to expect, covering 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?

Only one parameter 'days' with schema coverage 100%. Schema already explains the parameter clearly (lookback days, default 7). Description adds no further meaning, so 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?

Begins with 'Get the daily NZX market wrap' clearly identifying the verb and resource. Lists specific outputs (price moves, market breadth, announcements, etc.) distinguishing it from sibling tools like get_stock_prices which focus on individual stocks.

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 when to use: 'when asked about overall market conditions, today's market, what happened on the NZX, or market summary.' No explicit exclusions or alternatives, but context from siblings makes it 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 are provided, so the description carries full burden. It implies a read-only operation ('Get detailed profile') but does not explicitly state it does not modify data or require special permissions. It covers what data is returned but omits other behavioral context like error handling 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 two sentences with no wasted words. It front-loads the action and resource, then lists key data categories. Every sentence adds value, and the structure is easy 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 simple data retrieval tool with two well-documented parameters and no output schema, the description adequately covers purpose and content. It lists the main data categories returned. However, it lacks details on potential errors, pagination (if any), or the format of the include parameter's effect. Still, it is largely complete given the tool's simplicity.

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 both parameters (slug and include) already described. The tool description does not add meaning beyond summarizing the output categories; it does not elaborate on parameter formats or syntax 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 action: 'Get detailed profile for a specific director by slug.' It names the resource (director), the identifier (slug), and explicitly lists the data included (biography, board seats, compensation, share trades), distinguishing it from sibling tools like get_directors (likely lists) and get_insider_trades (trades only).

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

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

The description does not explicitly state when to use this tool over alternatives, nor does it provide exclusions or prerequisites. While the context of sibling tools and the descriptive phrase 'detailed profile for a specific director' implies its niche, explicit guidance on when not to use (e.g., for listing all directors, use get_directors) is missing.

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. It discloses that it returns name, bio, and board seats, which is adequate for a search tool. However, it does not mention default behavior (e.g., 'current' defaults to true) or any authentication 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 two sentences, front-loading purpose and return information before usage. It is concise without unnecessary 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?

The description covers what the tool returns but lacks mention of pagination (the 'limit' parameter) and the default value of 'current'. Given no output schema, more detail about return structure would improve 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?

The input schema has 100% coverage (all four parameters have descriptions). The description adds 'Filter by company or search by name' which restates two parameters but does not add meaning beyond the 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 verb 'Search' and resource 'NZX company directors', and specifies what is returned (name, bio, board seats). It distinguishes itself from sibling 'get_director_detail' by implying a broader search capability.

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 by company or searching by name, which provides some usage context, but does not explicitly state when to use this tool versus alternatives like 'get_director_detail' or provide 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 lists the data returned but fails to disclose whether changes are possible, authentication requirements, rate limits, or data freshness. The read-only nature is implied but not stated.

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 covering key output details. No extraneous words. Could benefit from structural improvements (e.g., bullet points) but is efficient overall.

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 parameters, no output schema, and no annotations, the description provides foundational context (NZX, dividend fields) but lacks information on parameter interactions, required input format, or typical use cases. Insufficient for complex queries.

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 adds no additional semantic meaning beyond the schema, so 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 tool retrieves dividend history for NZX companies, listing specific data elements (ex-date, payment date, DPS, etc.), which distinguishes it 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 use for dividend-related queries but does not explicitly state when to use this tool versus alternatives like get_financials or get_metrics. No exclusions or prerequisites are mentioned.

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 must disclose behavioral traits, but it only states the data source and included metrics. It omits information on required permissions, rate limits, pagination, or whether multiple calls are needed for full 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?

Two sentences, no filler. The first sentence immediately states the action, and the second adds relevant detail. 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?

Despite having 4 parameters, no output schema, and no annotations, the description is too brief. It lacks information on return structure, pagination, ordering, or how to handle ambiguous inputs. More context is needed for an agent to use it effectively.

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 documents all parameters. The description adds no extra meaning to parameters beyond naming a few output metrics. It does not explain valid values for 'year' or 'period', nor how 'limit' affects results.

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 earnings results for NZX companies, listing specific metrics (revenue, net profit, etc.) and noting the data source (announcements). This distinguishes it from sibling tools like get_financials, which likely provide 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?

No guidance on when to use this tool versus alternatives like get_financials or get_dividends. The description does not mention prerequisites, limitations, or scenarios where another tool 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?

No annotations exist, so the description must convey behavioral traits. It only lists data content and does not disclose safety (though 'Get' implies read-only), authentication requirements, pagination, rate limits, or any side effects. This is insufficient for a tool with no 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 includes specific counts (255 emissions records, etc.) that are informative but may not be essential for agent usage; it could be more concise. The first sentence is clear, but the list of categories makes it somewhat verbose.

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 adequately outlines the categories of data returned. However, it omits details like the structure of the response (single record vs. list), how year filtering affects results, and error conditions. It covers the main content but misses some 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 coverage is 100%, with both 'ticker' and 'year' already described in the input schema. The description does not add new meaning to the parameters beyond providing context on the data returned, which is helpful but not strictly additive. 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 it retrieves ESG data for NZX companies, listing specific categories (emissions, diversity, safety, reporting standards). This distinguishes it from sibling tools like get_financials or get_governance_scores, which focus on 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?

No guidance is provided on when to use this tool versus alternatives (e.g., get_governance_scores). There is no mention of prerequisites, typical use cases, or scenarios to avoid, leaving the agent without selection criteria.

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 describe behavior. It lacks details on data freshness, authentication, rate limits, or any side effects. As a read tool, it minimally addresses 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, directly stating purpose and capability. Every sentence adds value, with no fluff or repetition.

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

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

Given no output schema and no nested objects, the description covers the main inputs and outputs. It lacks any mention of pagination or data format, but for a simple retrieval tool this is sufficient.

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 parameter descriptions already exist. The description adds a summary ('Filter by statement type and year range') that provides browsing context but no additional semantic depth beyond what the schema already conveys.

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 financial statements for an NZX company, naming specific components (income, balance sheet, cash flow, ratios) and allowing filtering. This distinguishes it from sibling tools like get_dividends or get_earnings.

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 mentioning filtering capabilities, but does not explicitly state when to use this tool over alternatives like get_metrics or get_performance. No usage exclusions or prerequisites are provided.

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

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

No annotations exist, and the description lacks behavioral details such as read-only nature, data freshness, pagination, or error handling. It only implies a read operation via 'Get', which is basic.

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

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

Two sentences, front-loaded with purpose and components, no filler. 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 7 parameters and no output schema, the description explains the concept, scale, components, and filter options. It is mostly complete but lacks details on return structure or pagination.

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 parameter descriptions are already clear. The tool's description adds context about the score scale and components but doesn't enhance parameter understanding beyond what the schema provides. 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 the tool retrieves Governance Risk Scores for NZX companies, mentioning the 0-100 scale and six components. It differentiates from siblings like get_credit_ratings or get_esg_data by focusing on governance, but doesn't explicitly distinguish from related tools.

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, nor any exclusions or prerequisites. The description only mentions filter options, which are parameter usage, not usage 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?

The description discloses that the tool returns 'who is buying/selling, amounts, and dates', which informs the agent of the output content. However, it does not mention any access restrictions, rate limits, or data freshness. Since no annotations are provided, this is acceptable but could be more transparent.

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 long, front-loaded with the action and resource, and contains no extraneous words. 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 no output schema and no annotations, the description provides sufficient context: it explains the tool's purpose, the data it returns (who, amounts, dates), and its scope (NZX companies). It could mention ordering or default limits, but is mostly complete for a simple 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 description coverage is 100%, with each parameter having a clear description. The tool description adds no additional meaning beyond the schema, so 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 explicitly states the verb 'Get', resource 'director share transactions (insider trades)', and scope 'for NZX companies'. It distinguishes from siblings like 'get_dividends' and 'get_shareholders' by focusing on insider trading 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 implies usage by stating 'for NZX companies' and listing what is shown, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'get_substantial_holders'). No when-not or exclusions 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?

With no annotations, the description carries full burden. It adds the data range (Dec 2018 - Sep 2022) and output fields, but does not disclose whether returns latest data only or all available quarters, nor any rate limits or permissions needed.

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 that are front-loaded: first states the core function, second adds key details (output fields, date range). 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?

For a tool with 2 params and no output schema, the description covers purpose, output fields, data range, and date format. Minor gap: behavior when no date is provided is not explicitly stated (likely returns latest?), but otherwise 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 coverage is 100% but description adds value by explaining output fields (funds, market value, percentage) and the data range, and clarifies the date parameter format and optional nature. This exceeds 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 clearly states the tool retrieves KiwiSaver fund holdings for an NZX company, specifying the output includes fund names, market value, and percentage. It is distinct from sibling tools like get_shareholders or get_stock_prices, as it focuses specifically on KiwiSaver holdings.

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 needing KiwiSaver holdings data, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., get_shareholders, get_substantial_holders). No when-not or exclusions are mentioned.

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, so the description carries full burden. It transparently lists returned fields (roles, tenure, biographies, education, profile links), coverage numbers, data source ('shared.people'), and filter capability. No destructive actions are implied.

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 that front-loads the main purpose and key details. It is reasonably concise, though coverage statistics could be considered extraneous but informative. 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?

No output schema exists, so the description must explain return values. It thoroughly lists what is returned (roles, tenure, biographies, etc.), notes coverage (127 issuers, 508 executives), clarifies data origin ('profile data where linked to shared.people'), and mentions filtering. This is complete for a 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 adds context that role filters to normalized roles (e.g., CEO, CFO) and ticker is an NZX symbol, but this largely repeats the schema descriptions. No additional syntax or constraints beyond schema 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 'Get the management team (C-suite executives) for an NZX company' and specifies the returned data (CEO, CFO, etc.). This clearly distinguishes it from sibling tools like get_directors (board members) and get_company_detail (broader 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 mentions filtering by role but does not explicitly state when to use this tool versus alternatives. It provides context about coverage (127 issuers, 508 executives) but lacks explicit when-not 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?

No annotations are provided, so the description carries the full burden. It explains the return content (13 signal types) and mentions filtering by days, type, etc. It does not cover error behavior, rate limits, or data freshness, but it is transparent enough for an agent to understand what the tool does and its scope.

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 that efficiently conveys purpose, output, and usage. It could be slightly more structured with bullet points, but it is not overly verbose and is well-organized.

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 6 parameters, no output schema, and no annotations, the description provides a solid overview of the tool's capabilities, return types, and filter options. It is complete enough for an agent to select and invoke the tool correctly, though adding an example return structure would improve 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?

The schema covers 100% of parameters with descriptions, but the description adds context: 'days' default is 180 and suggests values for 'this week' and 'today', and 'type' is comma-separated with a list of values. This enriches the schema beyond what is 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 returns a unified stream of NZX market events, lists 13 specific signal types, and provides concrete usage examples like 'what happened on the NZX today/this week?' This distinguishes it from sibling tools that focus on individual signal 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 when to use this tool (for unified market activity queries) and gives many example questions. It implicitly suggests not to use it when a specific signal type is needed alone, as singular signal tools exist as 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 provided, so description must carry behavioral details. It lacks info on data freshness, rate limits, pagination, or the effect of mode (snapshot vs historical). The tool likely is read-only, but this is not stated.

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 succinct sentences: first states purpose, second details metric categories and usage. 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 many sibling tools (e.g., get_financials, get_performance), description should explain how this tool differs and what output to expect. It lacks detail on output structure (no output schema) and context on when to prefer this over alternatives.

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 100% of parameters with descriptions, so baseline is 3. Description adds value by listing example metrics (comprehensive_roe, oci_divergence) beyond schema, aiding 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?

Description clearly states 'Get financial metrics/ratios' for NZX companies and lists categories (profitability, leverage, etc.). This distinguishes it from sibling tools like get_financials (likely raw statements) but does not explicitly differentiate from get_performance or get_market_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?

The phrase 'Use for screening or comparison' implies when to use, but no explicit when-not-to-use or alternatives provided. Does not distinguish from similar tools like get_financials.

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 bears full burden of behavioral disclosure. It enumerates the return metrics (returns, alpha, volatility, range, market cap) and implies read-only behavior. It lacks details on data availability or historical depth but is sufficiently transparent for a non-destructive 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?

The description is two sentences, front-loading purpose and key outputs, then adding a use-case sentence. Every word serves a purpose, and there is no redundancy or unnecessary detail.

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 one-parameter, read-only tool with no output schema, the description covers purpose, outputs, and use case adequately. It could mention data limitations or historical range, but overall it equips an agent to 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% (one parameter 'ticker' with description 'NZX ticker symbol'). The description adds minor context ('for an NZX company') but does not significantly enhance the parameter's meaning beyond the schema. 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 the tool retrieves stock performance metrics for NZX companies, listing specific metrics (1d to 5y returns, alpha vs NZX50, volatility, 52-week range, market cap). This specificity distinguishes 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?

The description explicitly states 'Use for performance comparison and pay-for-performance analysis,' providing clear guidance on when to use the tool. It does not mention alternatives or exclusion criteria, but the stated use case is sufficient for most contexts.

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, so the description carries full weight. It discloses return fields (segment revenue, operating profit, assets) and units (NZD thousands), useful for an agent. It does not discuss side effects, but as a read operation this is acceptable.

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 only two sentences long, with the first sentence stating the action and return, and the second listing usage triggers. Every word earns its place, making it highly concise and 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 no output schema, the description adequately explains return values (segment data with specific fields and units). It covers the tool's scope (NZX companies) and parameters implicitly. Missing error handling or prerequisites, but acceptable 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 parameters are already documented. The description adds no additional meaning beyond the schema for parameters like 'type', 'year', or 'limit'. A score of 3 is appropriate per the baseline rule.

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 NZX companies, distinguishing it from sibling tools like get_financials by focusing specifically on segment data. It also lists example queries, reinforcing its purpose.

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 phrases (e.g., 'revenue breakdown', 'business segments') guiding when to use. It does not mention when not to use, but the context of sibling tools implies alternatives. This is still strong 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; description covers data sources, metrics (HHI, holder types, changes, voting power), and scope (top 20 + substantial holders). Does not disclose pagination but states data volume.

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 dense sentences efficiently conveying purpose, data scope, and usage hint. Minor structure improvement possible (e.g., separate usage from data overview).

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; description lists return data (HHI, holder types, changes, voting rights) and data source size. Sufficient for an experienced agent to understand output.

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 100% with ticker and year. Description adds '?all=true' which is not a parameter in the schema, potentially misleading. Year filtering is explained but ticker is not elaborated beyond 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 'Get top 20 shareholders and substantial holders (5%+) for an NZX company' with specific verb and resource. Differentiated from sibling 'get_substantial_holders' by combining both 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?

Provides data scale and usage example ('?year=2025 or ?all=true'). Lacks explicit guidance on when to use this combined tool vs. 'get_substantial_holders' sibling.

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 present, so description carries full burden. It indicates read-only operation ('Get') but does not disclose limitations like rate limits, data availability, or error handling. The description 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?

Two concise sentences, no redundancy. Every word adds value, front-loaded with the core action and scope.

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 and lack of output schema, the description provides sufficient context for an AI agent to understand its purpose and expected usage. Minor gap: no indication of the response format or pagination, but not critical for a price history 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?

The input schema covers all 4 parameters with descriptions (100% coverage). The tool description adds no additional meaning beyond naming the data source (NZX). Baseline score of 3 is appropriate since schema already does the heavy lifting.

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 daily stock price history (OHLCV) for NZX companies, using a specific verb ('Get') and resource ('stock price history'). It distinguishes well from sibling tools that retrieve other types of data (e.g., dividends, earnings, market 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?

The description mentions use cases ('price trends, returns, and technical context'), providing clear context for when to use. However, it lacks explicit guidance on when not to use or alternatives among siblings, which could further aid in tool 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?

With no annotations, the description carries the full burden and reveals data fields, record count, issuer count, and legal basis (NZX disclosure notices). It implies read-only behavior; however, it does not mention rate limits or explicit read-only guarantee.

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 that front-loads the main purpose, then lists fields and use cases efficiently. It is concise but could be slightly more 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 no output schema, it compensates by enumerating output fields. It mentions sibling relationships and use cases. However, it omits pagination or result format details, but remains mostly 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 coverage is 100%, and the description does not add extra details beyond the schema descriptions for ticker and include_ceased. Baseline score 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?

The description clearly identifies the tool as retrieving substantial shareholders (5%+ voting rights) for NZX companies from disclosure notices, and explicitly distinguishes it from the sibling get_shareholders tool which uses 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?

It provides specific use cases (block holder analysis, activist tracking, M&A signals, ownership concentration) and notes how it complements get_shareholders, but does not state when not to use it or list alternative tools for other scenarios.

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 must convey behavioral traits. It states the tool returns structured deal data and covers several deal categories, which is helpful. However, it omits details like error handling, data freshness, or whether it supports pagination, which would be valuable 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 concise with three sentences: purpose, output summary, and usage hints. It is front-loaded with the core action and avoids unnecessary fluff. 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 five parameters and no output schema, the description explains the tool's purpose and output structure. However, it does not integrate how parameters like status or deal_type affect results, and it lacks a summary of behavior for combined filters. Still, it is fairly complete for a straightforward 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 description coverage is 100%, so each parameter already has a clear description. The tool description adds context by listing deal types that correspond to the deal_type parameter, but overall it does not add significant new semantics 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 M&A and takeover activity for an NZX company, listing specific deal types (takeover offers, mergers, etc.) and output fields (acquirer, target, offer price, etc.). This differentiates it from sibling tools like get_dividends or get_earnings which cover different 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 lists example queries such as "takeovers", "M&A", "acquisitions", and "hostile bids" as triggers. This helps an agent decide when to use this tool. However, it does not mention when not to use it or specify alternatives among sibling tools, which would improve 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It lists the indicators returned, implying a read operation, but does not cover error handling (e.g., invalid ticker), rate limits, or security requirements. The description adds context about the indicators but lacks comprehensive behavioral 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 three sentences, front-loading the purpose, then listing indicators, then stating use cases. Every sentence adds value with no redundancy or unnecessary detail.

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 lack of an output schema, the description provides a reasonable list of expected indicators, which helps an agent understand the return content. However, it does not describe the response structure or format, which could be improved for 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 the ticker parameter already described as an NZX ticker symbol. The tool description confirms this but adds no additional semantic detail beyond the schema. Baseline at 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 technical analysis indicators for an NZX company, listing specific indicators (SMA, RSI, cross, etc.) and use cases. This distinguishes it from siblings like get_market_signals or get_metrics, which focus on different financial 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 explicitly states when to use the tool ('for trading signals, momentum analysis, and technical screening'), providing clear context. However, it does not mention when to avoid using it or explicitly contrast with alternatives among the 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?

With no annotations, the description discloses that the tool uses AI to extract data and returns cached results if previously extracted. This covers key behavioral aspects, though it could mention if any side effects exist (none apparent).

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 perfectly front-load purpose and capabilities. Every word adds value—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?

Despite no output schema, the description lists extracted items (summary, key figures, etc.) and explains caching behavior. Combined with single parameter and clear source, it covers all needed context for reliable 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?

The schema already describes the parameter, but the description adds an example ('12345') and ties it to search_announcements output, providing context beyond the schema's generic 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?

The description explicitly states the tool reads and analyzes a specific NZX announcement, extracting summary, key figures, sentiment, entities, and risk flags. It clearly distinguishes from sibling tools like search_announcements by focusing on a single announcement and its AI analysis.

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 instructs to provide the announcement_id from search_announcements results, giving a concrete example. It implies the tool should be used after searching, but does not explicitly list alternatives or state when not 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?

No annotations are provided, so the description bears full responsibility. It discloses that the tool searches titles and full document content, returns AI classifications and confidence scores, and may include sentiment, topics, risk flags, and summaries. It does not mention rate limits, pagination behavior, or any side effects, but the described behavior is thorough and non-destructive.

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 moderately concise, comprising three sentences. It front-loads the core action and scope, then lists result fields. While every sentence adds value, the enumeration of optional result fields could be slightly more compact. Overall, it is well-structured and not verbose.

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 absence of an output schema, the description adequately explains return fields (AI categories, sentiment, etc.). It covers the tool's purpose, parameters, and behavior. It does not mention prerequisites or error conditions, but for a search tool with optional parameters and rich results, the description is substantially 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 coverage is 100% with all 6 parameters described in the input schema. The description adds minimal extra meaning beyond the schema (e.g., 'searches both titles and full PDF document text' for q). The baseline of 3 is appropriate as the schema already carries the definition burden; the description provides general context but no supplementary parameter-specific 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 specifies a 'full-text search across 64,000+ NZX market announcements' with clear scope (2017-present, includes PDF text). It explicitly distinguishes from sibling tools that are getters for specific document types (e.g., get_annual_reports, get_board_changes). The verb 'search' is appropriate and the resource is unambiguously '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 states 'Use for finding mentions of specific topics, companies, people, or events across all NZX filings,' providing clear context. However, it does not explicitly exclude scenarios or name alternative tools when they would be more appropriate (e.g., using a specific getter for a single known announcement). The guidance is implied by the sibling tools but 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?

No annotations provided, so description carries full burden. It mentions returns but lacks details on pagination, behavior with no results, or sorting. Adequate but not fully transparent.

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, minimal waste, front-loaded with key information. 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 no output schema, the description provides basic return information. Might be sufficient for a simple search tool, though more detail on response structure would improve 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 descriptions for all parameters. The description adds context like examples and default limit, but does not meaningfully supplement the schema's parameter 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 verb (search), resource (NZX-listed companies), and what it returns (list with sector, market cap). It distinguishes from sibling tools which mostly require a specific ticker, as it is for finding a ticker first.

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 to find a company ticker before calling other tools,' providing clear guidance on when to use this tool versus the many get_* tools that require a known ticker.

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