NZXplorer (Remote)

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: '$0 cost (pure regex/heuristic)' discloses the method and cost profile, 'POST endpoint — requires draft_text in body' clarifies transport, and 'Uses NZXplorer historical NZX language and sentiment data' identifies the data source driving the analysis.

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?

Purpose and scope are front-loaded in the first sentence, followed by compact feature enumeration. The middle run-on of capabilities is dense and partially redundant (superlatives vs corporate buzzwords; sentiment vs media pickup), but nearly every clause carries actionable information about what the tool returns.

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

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

With an output schema present, the description need not detail return values, and annotations cover the safety profile. Combined with its thorough enumeration of analysis dimensions and explicit method/cost/source disclosure, the definition is complete enough for an agent to select and call 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 description coverage is 100% with only two parameters, so the schema already documents ticker and draft_text including format and length limits. The description only restates that draft_text is required in the body, adding no syntax or semantic detail beyond the schema. Baseline 3 per the coverage 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?

States a specific verb (Analyse) and resource (draft NZX announcement) with the pre-publication scope clearly delineated. The enumerated scan categories (FMA compliance risk, defamation, superlatives, forward-looking statements, buried risks) make it unmistakably distinct from sibling tools like analyse_narrative_risk or get_disclosure_language, which operate on already-published content.

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 via 'before publication' and 'useful for IR teams, company secretaries, and communications professionals', giving an audience and timing context. However, it names no alternative tool and gives no explicit when-not guidance, leaving the agent to infer that this is for drafts rather than existing announcements.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description goes further by disclosing the underlying engine (IR Rehearsal + company context + optional Claude Haiku), a concrete cost (~$0.10), and the required input. The 'POST endpoint' note is transport-level and, since the result is a non-persisted simulation, does not contradict readOnlyHint.

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

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

Four tight sentences, each front-loaded with the purpose first, then outputs, then engine/cost, then the input requirement. No filler; the enumeration of return fields is arguably redundant given an output schema but it doubles as scoping and stays compact.

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 two-parameter simulation with an output schema and full annotation coverage, the description supplies the cost, engine, required input, and what the score/outputs look like. The only omission is guidance on interpreting the 0-100 score or how it compares to sibling analyses, which is minor.

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 both parameters (ticker example, draft_text length bounds), so the schema carries the semantics. The description only restates 'requires draft_text' and adds nothing about format, ticker validity, or cost-driving length. Baseline 3 is correct.

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

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

States a specific verb + resource + scope: multi-stakeholder narrative risk simulation for a draft NZX announcement, and names the exact stakeholder set (institutions, retail, media, analysts, regulators). That is enough to distinguish it from siblings like analyse_ir_draft, simulate_event, simulate_investor_qa and get_narrative_tracker.

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

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

Usage is implied by 'for a draft NZX announcement' plus the 'requires draft_text' note, which tells the agent the necessary precondition. However, no sibling is named and there is no explicit statement of when to pick this over analyse_ir_draft or simulate_investor_qa, so routing is left to inference.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real context beyond that: the nine evaluated dimensions, the eight named presets, and the return structure (per-company pass/fail with rule breakdown plus aggregate stats). No auth or rate-limit notes, but the added behavioral detail is substantial.

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

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

Front-loads the purpose, then the evaluated dimensions, presets, and return shape. It is efficient overall, though enumerating all eight preset IDs duplicates the schema's preset description and the nine-dimension list is somewhat long, preventing a perfect score.

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

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

An output schema exists, so the return-value explanation is not strictly required, and the annotations carry the safety profile; the description still supplies scope, dimensions, and presets. The one loose end is 'configurable thresholds', which no parameter exposes (nor does the schema), leaving a minor ambiguity about how thresholds are tuned.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, including the full preset list and the ticker default of all companies. The description mirrors this ('8 presets available', 'all NZX companies (or a subset)') without adding format or syntax meaning, so baseline 3 applies.

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

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

States a specific verb+resource ('Run a governance policy compliance check') and immediately narrows scope to NZX companies. It enumerates the nine governance dimensions it evaluates, which distinguishes it from sibling score tools like get_governance_scorecard or get_governance_scores that report scores rather than run policy screens.

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 final sentence gives explicit trigger conditions ('governance compliance, policy screening, institutional governance standards, or market-wide governance scanning'), which is clear when-to-use guidance. It stops short of naming a specific alternative sibling or stating when NOT to use it, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the external source register, that results are TTL-filtered, and the licensing constraint (MBIE Agreement cl 4.5-4.6). The 'any person in the NZXplorer database' scoping is also consistent with openWorldHint=false.

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

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

Front-loaded with the action and data source, then coverage, then when-to-use. Mostly waste-free, but the trailing 'Uses person slug' sentence duplicates the schema and could be dropped.

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?

Output schema exists, so return formatting need not be described. For a single-parameter, read-only lookup the description covers source, filtering rule, and selection context; nothing an agent needs to invoke it correctly is missing.

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

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

One parameter at 100% schema coverage, so the schema already documents slug (including the 'john-smith' format and its shared.people origin). The description's 'Uses person slug' adds essentially nothing beyond the schema; baseline 3 applies.

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

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

Specific verb (check) plus resource (insolvency/bankruptcy history), names the backing source (MBIE Insolvency Register) and the three record types covered (bankruptcy, no-asset procedures, summary instalment orders). An agent can distinguish this from near neighbours like get_director_due_diligence or get_litigation_history without opening the schema.

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

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

Explicit use cases are given: insolvency history, bankruptcy status, financial fitness to serve as director, and due diligence screening. There is no when-not guidance or named alternative tool for adjacent checks, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious context: the comparison method (thesis direction vs. four independent signals) and the invalidation score scale of 0-100. Auth, limits and failure modes remain unstated.

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

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

Three dense sentences, front-loaded with the purpose, then the comparison logic, then the return shape. No filler 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?

Inputs are just ticker plus direction, and an output schema already documents the return shape, so the description's explanation of the signal breakdown and score range is more than sufficient. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the enum for direction is documented in the schema, so the description's restatement of bullish/bearish/neutral adds nothing beyond structured fields. Baseline 3 is correct when the schema does the work.

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

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

States a specific verb and resource ('Check if an investment thesis for an NZX company is still valid') and enumerates the four signals it aggregates, which distinguishes it from sibling signal tools like get_analyst_consensus and get_fair_value. An agent can tell this is the composite validity check rather than an individual data fetch.

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 the use case (you hold a thesis direction and want to test its validity) but never states when to use this versus the individual signal tools it wraps, nor any exclusions. Honestly adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuine context with '128 issuers scored', signalling coverage limits, but says nothing about how scores are sourced or refreshed. No contradiction with annotations.

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

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

Three short sentences, front-loaded with the core purpose, then the metric breakdown, then the coverage figure. Zero filler and nothing redundant.

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

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

An output schema exists, so return-value detail is unnecessary, and annotations cover the safety profile. What remains missing is routing guidance among the many financial-scoring siblings, but the core definition is otherwise complete for a 3-param read 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 ticker, year, and limit are already documented in the schema (including range syntax and ticker examples). The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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

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

States a specific verb ('Get') and resource (accounting quality scores) scoped to NZX companies, then enumerates the exact metrics returned (Beneish M, Piotroski F, Altman Z, interest coverage, current ratio). This lets an agent distinguish it from siblings like get_earnings_quality or get_financial_distress without opening the schema.

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

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

The description never says when to use this tool versus alternatives such as get_earnings_quality, get_financial_distress, or get_financials, nor does it state prerequisites. Usage is only implied by the metric list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description usefully adds that this is a derived composite score with a defined factor set and ordinal rating bands, which tells the agent what kind of value to expect. It doesn't discuss data freshness or coverage caveats, so not a 5.

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

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

Front-loads the purpose and score definition, then the factor list, then the rating scale, then usage triggers. Every sentence carries information, though the eight-factor enumeration is dense and could be trimmed without much loss.

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

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

An output schema exists, so return values need not be explained. The description covers what the score means, its components, its range and rating bands, and when to call it — enough for an agent to invoke correctly given the single well-documented parameter.

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

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

Schema description coverage is 100% and there is a single ticker parameter whose format is fully documented in the schema. The description adds no parameter-level detail beyond the implicit NZX scope, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get activist vulnerability score for an NZX company') and immediately defines the composite: 8 factors, 0-100 scale, rating bands. An agent can distinguish this from siblings like get_governance_scorecard or get_takeover_probability without opening the schema.

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

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

Explicit when-to-use triggers are given ('activist risk, governance vulnerability, board accountability, whether a company could be an activist target'), which is clear positive routing. However, it names no alternative tool or exclusion condition (e.g. when to prefer get_governance_scorecard instead), so it stops short of full 5-level guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description usefully adds scope detail (annual vs quarterly, count vs value, sector specialization, historical trends), but says nothing about result granularity, pagination, or how the ranking universe is defined.

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, front-loaded with the core resource and its dimensions, with no filler or restatement of the title. The middle sentence is slightly promotional ('dominate NZX capital markets') but still carries informational content.

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

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

For a no-parameter, read-only tool with an output schema and rich annotations, the description gives enough context to know what data comes back and over what periods. Only the sibling disambiguation and any coverage-scope caveats are 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?

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. Schema coverage is reported at 100% with an empty property set, confirming no parameter burden.

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

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

The description names a specific resource (NZX deal adviser league tables) and states what it contains: annual/quarterly rankings by deal count and value, plus sector specialization and trends. It is clear on its own, though it never distinguishes itself from the nearby sibling get_deal_advisers, which an agent could easily confuse it with.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. With get_deal_advisers in the sibling list covering a closely related concept, the absence of any routing guidance is a real gap; usage can only be inferred from the subject matter.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is carried. The description still adds real behavioral context beyond them: it discloses the two upstream data sources, the AR vs GETS value semantics, and that mode (c) returns a bounded top-25-per-side summary. It doesn't discuss recency or coverage gaps of the sources.

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

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

Front-loaded with the core concept, then structured into sources, modes, use cases, and value legend. Roughly 110 words that each carry distinct information; no filler or 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?

With an output schema present, return-value documentation is unnecessary and the description correctly focuses on inputs, sourcing, and mode behavior. For a zero-required-parameter lookup tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above it by explaining what each parameter selects (agency→charities, charity→agencies, neither→platform summary) and illustrating accepted slug/name formats. It doesn't restate the limit default beyond what the schema already documents.

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

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

States a specific verb+resource ('agency↔charity funding graph') and decomposes it into two named data sources and three call modes. An agent can determine exactly what this returns without opening the schema. This meaningfully distinguishes it from generic siblings like get_government_contracts or get_corporate_giving.

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 three modes (a/b/c) give explicit when-to-use conditions keyed to which parameter is passed, and the example questions ('which charities does MSD fund', 'who funds Women's Refuge') anchor intent. It lacks explicit exclusions or named alternative siblings, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description goes beyond that by disclosing the enrichment contents and the presence of compound directives and machine-readable suggested actions, which tells the agent this returns pre-analyzed signals rather than raw events.

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 what the tool returns and then the selection guidance. The content enumeration is slightly list-heavy but every item earns its place by signaling available signal types.

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

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

An output schema exists to carry return structure and annotations carry the safety profile, so the description only needs to convey purpose, enrichment scope and routing. It does all three; the only omission is any note on data freshness or coverage universe, which the schema's lookback params partially imply.

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 days, limit, types, tickers and severity are all documented in the schema itself. The description adds no format, default or interaction detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get enriched market events') and enumerates the payload (governance scores, insider conviction, dividend safety, compound directives, suggested actions). It distinguishes itself from the broader family by positioning as an aggregator, but it never names a concrete sibling (e.g. get_market_signals, get_morning_brief) that an agent might otherwise pick.

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

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

'Use this instead of multiple individual lookups when you need to understand what is happening at a company' gives a clear selection condition for the aggregate-over-singular choice. There is no explicit when-not guidance or named alternative, so it stops short of a 5.

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

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

Annotations already establish the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description is only obligated to add context. It does: the output is '~80% complete' and is intended for company secretary review, which is a genuinely useful quality/trust disclosure an agent would not get from the annotations.

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

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

Three sentences, front-loaded with the purpose, then content scope, then use trigger — no filler or marketing language. Minor overlap between 'Generate an automated draft' and 'Produces ~80% complete draft', but nothing wasteful enough to penalize further.

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

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

An output schema exists, so return structure need not be described. For a one-parameter generator, the description covers what it produces, how complete it is, and when to invoke it — nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% for the single ticker parameter, so the schema fully documents it and the description adds no syntax or format detail beyond it. Baseline 3 applies when structured fields carry the parameter burden.

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

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

States a specific verb and resource ('Generate an automated draft Notice of Annual Meeting') plus the exact jurisdiction (NZX company). It also enumerates the substantive content the draft covers (re-election rotation, auditor re-appointment, fee pool, capital raise ratifications), which cleanly separates it from retrieval siblings like get_agm_resolutions or predictive ones like predict_agm_outcome.

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?

Gives a clear use trigger: 'Use when asked about AGM preparation, meeting notices, director re-election, or proxy forms.' That is strong contextual guidance, but it names no alternative tool and does not state when NOT to use it (e.g. a proxy forms request against a different 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?

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

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

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

Two short sentences with no filler or redundancy: the first states what the tool returns, and the second gives the use case. The key scoping element is front-loaded.

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents ticker and year. The description adds no meaning beyond 'voting data for an NZX company,' which only reinforces the obvious ticker parameter, so it stays at the baseline 3.

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

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

The description names a specific verb ('Get'), a specific resource ('AGM resolution voting data'), and a scope ('for an NZX company'). It also lists the concrete data elements (votes for/against/abstain, pass/fail, support percentages), which distinguishes it from related governance siblings like get_governance_scores and get_board_changes.

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

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

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

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear without the description. The description adds useful content about what the analysis includes (sentiment, conviction, hedging, key themes), but it does not disclose operational behavior such as rate limits, data freshness, or historical coverage beyond the year parameter.

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 four short sentences, front-loaded with the core action and resource. It avoids repetition and waste, though it could be slightly tighter by merging the LIS and content sentences.

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

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

An output schema exists, so return values need not be explained in the description. With read-only annotations and complete parameter descriptions, the definition is largely self-contained. It could mention whether the analysis covers historical AGMs by default or requires the year filter, but otherwise it is complete for this 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 schema already documents ticker, role, and year. The description does not add syntax, format, or filtering semantics beyond what is already in the schema. The baseline score of 3 is appropriate when the schema carries the full parameter burden.

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

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

The description states a specific verb and resource: 'Get AGM speech analysis for an NZX company.' It also clarifies the analytical content (LIS, sentiment, conviction, hedging, key themes), which distinguishes it from sibling tools like get_agm_resolutions or get_agm_notice_draft. However, it does not explicitly contrast itself with other language-analysis siblings such as get_disclosure_language or get_transcript_diffs.

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 gives a usage context: 'Use for governance quality and management communication analysis.' That implies when the tool is relevant, but it does not state when not to use it or name alternative tools for related questions. The guidance is present but minimal.

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

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

Annotations already declare this a safe, idempotent, non-destructive read, so the safety profile is covered. The description adds genuinely useful method context (Qlib-inspired, IC analysis over 36 metrics) but says nothing about coverage limits, freshness, latency, or cost for an analytical scoring 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?

Three sentences, no filler, and the core deliverable (composite alpha score across 1M/3M/12M horizons) is front-loaded. It is somewhat dense in enumeration but every clause carries 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?

An output schema exists, so the enumerated return fields are redundant but harmless; scope (NZX), method, and inputs are all stated. The remaining gap is comparative context versus the many closely named factor/alpha siblings, which matters given this crowded tool family.

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 ticker parameter with 100% schema description coverage, including examples ('AIR', 'FPH', 'MEL'), so the schema fully carries semantics. The description adds only the NZX scope constraint, which is baseline-level value for a 1-param tool.

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

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

States a specific verb and resource ('Get Qlib-inspired alpha factor scores') and names the scope (NZX company) plus what the score is built from (36 fundamental/technical/governance metrics). However, it offers no differentiation from close siblings such as get_alpha_score, get_factor_model, get_factor_grades, or get_factor_validation, so an agent cannot tell which of these to pick from the description alone.

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 lists intended use cases ('quantitative analysis, factor exposure, alpha signals, or stock scoring'), which is clear enough context. But it names no alternatives and gives no when-not guidance, and 'stock scoring' overlaps heavily with sibling tools like get_alpha_score and screen_stocks, so routing remains ambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the bar is lower. The description still adds real context beyond them: the signals are proprietary, backtested over 10 years of NZX data, and flagged with 'validated alpha spreads', which honestly frames the score's provenance and 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?

Purpose is front-loaded in the first clause, followed by the component list and return shape. It is dense but each sentence carries information; the backtest sentence is slightly promotional yet relevant to interpreting the score.

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

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

With an output schema present, return values need no elaboration, yet the description still summarises score, rating band, breakdown and active flags. For a one-parameter read tool with full annotation coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter and schema coverage is 100%, with the schema itself giving format examples ("FPH", "AIR"). The description adds nothing about the ticker beyond 'NZX company', so the baseline 3 applies.

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

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

Specific verb ('Get') plus a precisely scoped resource: a composite 0-100 alpha score for an NZX company, with the five constituent dimensions named. This clearly separates it from raw-factor siblings such as get_alpha_factors, get_factor_model and get_factor_grades, which surface individual signals rather than a single composite score.

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 the use case (a single aggregate alpha read on an NZX company) but never states when to prefer it over get_alpha_factors, get_factor_grades or get_factor_validation, nor any exclusions or prerequisites. Usage is inferable but not guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered structurally. The description adds one useful behavioral fact beyond that: the result is a 'latest consensus snapshot' (point-in-time, not a time series), which helps the agent set expectations. It adds nothing on staleness, refresh cadence, or coverage gaps.

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?

One sentence, front-loaded with the verb and resource, then a compact enumeration of returned fields. No filler. Slightly long due to the field list, but each item earns its place by telling the agent what to expect.

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

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

An output schema exists, so return formatting need not be explained, and rich annotations cover the safety profile. The description is complete enough for a one-parameter read tool, with the only real gap being explicit routing relative to sibling consensus/coverage tools.

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?

There is a single parameter with 100% schema description coverage, including inline examples ('AIR', 'SPK', 'FPH'), so the schema already carries the meaning. The description reinforces NZX scoping but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Get) and resource (analyst consensus data for an NZX company) and enumerates the payload: rating, analyst count, target prices, buy/hold/sell breakdown, covering brokers. An agent can tell it apart from most siblings, though it does not explicitly distinguish itself from the close siblings get_consensus_estimates or get_broker_coverage.

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

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

There is no when-to-use guidance, no mention of alternatives, and no prerequisites. The only contextual cue is 'Returns the latest consensus snapshot', which implies point-in-time data but does not tell the agent when to prefer this over get_consensus_estimates.

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

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

Annotations already establish the safe read profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description still adds real context: results are scoped to the authenticated user and limited to "active" configurations, and the matching dimensions (keyword, announcement type, ticker, sector) are disclosed.

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 verb and resource, no filler or restatement of the title. Every clause contributes new information about scope or payload.

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

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

An output schema exists, so return-value detail is not required here; the description nonetheless summarizes what comes back. For a zero-parameter read tool the definition is essentially complete, with the only shortfall being the absence of routing guidance against the many sibling alert tools.

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 tool takes zero parameters, so the schema has nothing to document and there is no parameter semantics to add. The mention of keyword/type/ticker/sector describes what the stored alerts match on, not call arguments, which is harmless clarification rather than a gap.

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

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

States a specific verb ("List") and a specific resource ("the authenticated user's announcement alert subscriptions"), and further narrows the payload to "active alert configurations for NZX announcement content." It is clear what the tool does, though it never distinguishes itself from near-neighbors like list_alert_subscriptions or get_keyword_alerts.

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 scope ("the authenticated user's") but gives no explicit when-to-use or when-not-to-use guidance, and names no alternative. With siblings such as list_alert_subscriptions, get_keyword_alerts, and the subscribe_* alert tools in the same namespace, an agent gets no signal for choosing among them.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The 'AI-scored' wording signals derived rather than raw data, which is mild added context, but nothing is said about scoring latency, coverage gaps, or empty-result behavior for a company with no announcements.

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

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

Two tight sentences with the core purpose front-loaded and the return detail following. No filler, though the enumerated return fields are somewhat list-like and redundant given an output schema exists.

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?

Output schema exists so return values need not be explained, yet the description spends its second sentence doing exactly that. Combined with full annotation coverage and 100% schema coverage, the only real omission is routing guidance against sibling sentiment tools.

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

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

Schema description coverage is 100%, so all six parameters (ticker, from, to, limit, hedging, sentiment filters) are already documented in the schema. The description adds no filter syntax or default behavior beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: AI-scored sentiment analysis of NZX announcements for a company, plus the scope (-1 to +1 scores, confidence, hedging). Clear and non-tautological. However, it never differentiates itself from close siblings such as get_news_sentiment, get_capital_raise_sentiment, or get_disclosure_language, leaving the agent to guess which sentiment surface applies.

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

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

There is no when-to-use guidance, no when-not-to-use, no prerequisites, and no named alternative among the many sibling sentiment/disclosure tools. The description only says what the tool returns, not the situation that selects it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond that: the eight scoring dimensions, the 0-100 range, sector benchmarking with percentile, and the five rating bands — enough for an agent to understand what the returned score means.

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

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

Front-loaded with the core purpose, then the scoring model, then the use cases. The dimension enumeration is long but each item is informative rather than filler, and there is no redundant restatement of annotations or schema.

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

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

An output schema exists, so return values need no explanation, and the description still supplies the interpretive context (dimension set, scale, sector percentile, rating bands) an agent needs to use the result. Combined with full param coverage and confirming annotations, nothing material 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?

Only one parameter, and the schema already documents it at 100% coverage including NZX ticker examples ('FPH', 'AIR', 'SPK'). The description adds nothing about ticker format or resolution beyond what the schema provides, so the baseline of 3 applies.

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

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

Specific verb+resource ('Get annual report quality score for an NZX company') with the composite's composition, 0-100 scale, rating bands, and sector percentile made explicit. The dimension list implicitly separates it from siblings like get_disclosure_score or get_ir_quality, but it never names or contrasts an adjacent tool, so it stops short of full sibling differentiation.

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 final sentence gives clear triggering contexts: annual report quality, disclosure completeness, reporting standards, and reporting transparency. It states when to use it but offers no when-not-to-use guidance or routing to similar-scoring siblings such as get_disclosure_score or get_accounting_quality.

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

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

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

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

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

Two sentences, zero filler, and the core function is stated first. The usage guidance is a natural second sentence with no redundancy.

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description does not add meaningful parameter semantics beyond that baseline.

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

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

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

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

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

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

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld=false, non-destructive), so the bar is lower. The description adds substantive scope context — it is an early-warning cross-market scanner over all NZX companies with a defined detection taxonomy — which tells the agent what breadth of results to expect. It stops short of noting result limits or pagination 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?

Front-loads the core purpose, then the detection list, then triggers, then routing — a sensible order. The 16-item anomaly enumeration and the trigger-phrase list are somewhat verbose, but each block carries distinct information an agent needs for selection.

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

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

An output schema exists, so return-format detail is unnecessary. Combined with the annotations and full schema coverage, the description supplies everything needed to pick this tool over its siblings and call it correctly with zero required parameters.

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

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

Schema description coverage is 100%, so all five filters (days, sector, ticker, category, severity) are already documented in the schema. The description does not mention any parameter or its defaults, so it adds no meaning beyond the schema; the baseline 3 applies. The 7-category taxonomy mentioned loosely relates to the category filter but does not map cleanly onto its five enum 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?

States a specific verb+resource (market anomaly detection results) and concretely enumerates the 16 anomaly types across 7 categories, so the agent knows exactly what signal is returned. It also explicitly distinguishes itself from sibling company-level tools via the ROUTING block.

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?

Gives explicit trigger phrases ('red flags', 'warning signs', 'governance concerns across the market') and a clear when-not rule: use it only to find WHICH companies show patterns, and prefer get_governance_scores, get_agm_resolutions, get_audit_history, get_capital_raises when a company is already named. Alternatives and the selecting condition are both spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds no behavior beyond the data surface — no auth requirements, latency, or coverage caveats — and its field list largely restates the return payload that the output schema already carries.

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 core action and followed by triggers; nothing is wasted. The enumerated return fields are slightly redundant against the output schema but do help an agent scan relevance 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?

With an output schema present, the description need not explain return values, and it correctly focuses on scope and triggers. The one gap is sibling disambiguation against get_auditor_red_flags, which an agent choosing between the two would need.

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?

There is a single parameter with 100% schema description coverage, so the schema already documents the NZX ticker format and examples. The description only implies the ticker via 'for an NZX company' and adds no syntax or validation detail beyond the schema, making the baseline 3 correct.

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

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

States a specific verb and resource ('Get audit opinion history and red flags') scoped to NZX companies, and enumerates the returned content (auditor, opinion type, going concern, fees, risk signals). It does not, however, distinguish itself from the sibling get_auditor_red_flags, which appears to overlap heavily.

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 second sentence gives explicit trigger topics ('audit risk, auditor, going concern, audit opinion, audit fees, or auditor independence'), which is clear context for invocation. It stops short of naming alternatives or stating when NOT to use this tool versus the related auditor-red-flags 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description earns credit by disclosing the substantive thresholds and classification scheme an agent needs to interpret results: tenure >10 years, non-audit fee ratio >1.0, and a critical/high/elevated/moderate/low composite scale.

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: the first front-loads the resource and its full output inventory, the second is a pure routing cue. The dense enumeration is all load-bearing and nothing is redundant.

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

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

With an output schema present the description need not detail return formatting, and annotations cover safety. Combined with the enumerated signal set and trigger conditions, an agent has everything needed to select and invoke this 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?

There is one parameter with 100% schema description coverage (NZX ticker with examples), so the schema carries full parameter load. The description adds no format or constraint detail beyond what the schema already provides, making the baseline 3 the correct score.

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

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

States a specific verb and resource (get auditor red flags/risk signals for an NZX company) and then enumerates exactly what is returned: audit opinions, going concern warnings, tenure concerns, fee ratio issues, KAM counts, auditor changes, and a composite risk level. This level of specificity clearly separates it from broad siblings like get_audit_history or get_earnings_quality.

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 final sentence gives explicit trigger phrases ('audit red flags, auditor risk, auditor independence, going concern, or audit quality'), which is strong contextual guidance. It does not, however, name a competing sibling (e.g. get_audit_history) or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context. It delivers that by disclosing the reconstruction methodology and the four categories of output (direct holders, nominee breakdowns with identified fund managers, fund holdings, substantial holders), which tells the agent this is an aggregated/derived view rather than a live feed.

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

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

Three tight sentences: purpose first, methodology second, return contents third. No filler and the scope ('for an NZX issuer') is front-loaded.

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

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

With annotations covering safety and an output schema present, the definition is nearly complete for a single-parameter read tool. The only gap is the absence of routing guidance against the many ownership-adjacent siblings, which is minor given the distinctive 'beneficial/reconstructed' framing.

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 ticker parameter with 100% schema description coverage and a concrete example ('FPH', 'SPK', 'AIR'), so the schema carries the semantics. The description adds no further parameter detail, which is the expected baseline when coverage is complete.

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

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

States a specific verb and resource (get reconstructed beneficial ownership) scoped to an NZX issuer, and the methodology clause ('cross-references top-20 shareholder registers with fund manager holdings and custodian mappings') makes clear this is a derived analysis rather than a raw register dump. It distinguishes itself conceptually from siblings like get_shareholders and get_substantial_holders, but never names them.

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

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

Usage is implied rather than stated: the emphasis on identifying 'who is behind nominee/custodian entries' suggests you reach for this when raw holder registers are insufficient, but no explicit when-to-use, when-not-to-use, or alternative (e.g. get_shareholders) is given. An agent must infer the routing decision.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description's genuinely additive behavioural detail is the comparison universe (sector and market-cap peers) and that results are percentile-based against it. The remaining disclosure (percentiles, P25/P75, trend, assessment) restates output that the output schema already carries.

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

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

Two tight sentences, purpose and comparison scope front-loaded. The second sentence is largely a return-value inventory that the output schema already supplies, so it is slightly less economical than it could be, but nothing is padded or repeated.

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

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

With one fully documented parameter, complete annotations and an output schema, the only genuine gaps are scope (NZX-only market) and routing versus sibling board tools. The description covers what the tool computes and against whom, which is enough to invoke it correctly.

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

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

Single required parameter with 100% schema description coverage; the schema already defines 'ticker' as an NZX symbol with examples. The description adds nothing about the parameter, which is acceptable given full schema coverage, but it neither warns about unsupported tickers nor references the NZX-only scope.

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

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

States a specific verb and resource ('Get quantitative board benchmarking') and pins the comparison universe to sector and market-cap peers, with the six dimensions enumerated. An agent can distinguish it from pure composition or health-score siblings. It stops short of naming which sibling to prefer, so it never fully disambiguates within the crowded board-* family.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The neighbouring tools include get_board_health_score, get_board_effectiveness, get_board_composition_report, get_board_skills_matrix and get_compensation_benchmark, and nothing in the description tells the agent which of these this replaces or complements. Usage is only inferable from the 'benchmarking vs peers' framing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds scope value by disclosing that this is a composite briefing spanning eight analysis areas, but it says nothing about breadth cost, data freshness, or how the sections are assembled.

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 core purpose before the content list. The enumeration is long but each item earns its place by defining the briefing's scope; a slight trim of the list is possible without losing meaning.

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

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

An output schema exists, so return-value structure need not be explained, and annotations carry the safety profile. The description is adequate for an agent to know what the tool returns and when it is broadly relevant, with only the usage-routing detail left implicit.

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?

There is one parameter with 100% schema coverage, and the schema already documents ticker as an NZX ticker symbol. The description adds no format, constraint, or example detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (board meeting preparation briefing) and enumerates the component analyses it bundles (governance scores, insider activity, dividend analysis, financial health, AGM status, board changes). This distinguishes it as an aggregate/multi-section briefing rather than a single-metric sibling like get_board_composition_report. It stops short of explicitly naming the alternative tools it supersedes.

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 'board meeting preparation briefing' implies the intended use case, but there is no explicit when-to-use, when-not-to-use, or reference to alternatives such as get_ir_briefing or get_board_health_score. Usage is only inferable from the name and the enumerated content.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying that the output includes 'dates and reasons', which is useful for understanding what the tool returns. No contradictions with annotations.

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

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

Two sentences with no redundancy. The main purpose is front-loaded, and the additional detail about dates and reasons is concise and relevant. Every word earns its place.

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

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

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

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

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

Schema description coverage is 100%, so all parameters (to, from, limit, action, ticker) are already documented in the schema. The description does not add extra meaning beyond mentioning that results include dates and reasons, which relates to the from/to parameters but does not expand on syntax or format. Baseline 3 is appropriate given the high coverage.

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

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

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

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

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

The description implies usage for historical board changes via 'over time', but does not explicitly mention alternatives or when not to use it. It lacks explicit routing to siblings like get_directors for current composition, so guidance is only implied, not stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the report returns risk flags and benchmarking against the NZX Code and sector averages, telling the agent what kind of analysis comes back.

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, front-loaded with purpose followed by analysis scope and trigger conditions. The long nine-item enumeration is dense but each item genuinely delimits the report's coverage, so little is wasted.

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

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

With an output schema present, the description needn't detail return values, yet it still signals the risk-flag and benchmark outputs. Combined with full annotation coverage and a single well-documented parameter, the definition is complete enough 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?

Only one parameter (ticker) at 100% schema description coverage, so the schema fully documents it with examples. The description adds no format or validation detail beyond what the schema already provides; baseline 3 applies.

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

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

States a specific verb and resource ('Get a comprehensive board composition analytics report for an NZX company') and enumerates the nine analysis dimensions, so an agent knows exactly what the tool produces. It does not explicitly distinguish itself from overlapping siblings like get_board_benchmark or get_board_skills_matrix, which is the only gap.

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 final sentence gives an explicit trigger list (board composition, governance quality, board diversity, succession planning, nomination committee analysis), which is strong positive guidance. It offers no when-not conditions or named alternatives despite heavy sibling overlap.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds scope context ('all current directors') and enumerates the credential categories, which is useful, but says nothing about permissions, rate limits, or data freshness beyond that.

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 purpose, and the exhaustive parenthetical lists of degrees and designations are informative. Slight redundancy between the first sentence's 'qualifications, credentials, universities' and the second sentence's enumeration, but no genuine waste.

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

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

An output schema exists, so return values need not be explained, and the single required parameter is fully documented by the schema. For a read-only, one-param lookup the description is nearly complete; the only gap is the absence of sibling disambiguation against closely overlapping board/director tools.

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 single ticker parameter is documented with examples ('FPH', 'AIR', 'SPK') in the schema itself. The description adds nothing about parameter format or constraints, so the baseline 3 applies when the schema does all the work.

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

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

States a specific verb (Get) and resource (board credentials) and enumerates the concrete content: degrees, professional designations, governance certifications, university backgrounds, and credential gaps. An agent can tell what data comes back, but the description never distinguishes this from overlapping siblings such as get_iod_designations or get_board_skills_matrix.

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

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

There is no when-to-use guidance, no when-not-to-use, and no named alternative. The only implicit signal is that it applies to 'an NZX company,' leaving the agent to infer on its own whether to call this versus get_iod_designations, get_director_demographics, or get_board_skills_matrix.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds a useful breadth list of what the dashboard covers, but does not disclose behavior beyond what the output schema presumably shows (e.g., freshness, aggregation limits, or sourcing).

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

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

One densely packed sentence front-loads the purpose and lists components efficiently. Nothing is wasted, though the long em-dash enumeration makes it list-heavy rather than optimally structured.

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

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

With an output schema covering return values and annotations covering the safety profile, the main remaining gap is routing: the description never says when this aggregate view is preferable to the dozen-plus overlapping board siblings. For a broad dashboard tool in a crowded namespace, that omission is a real incompleteness.

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 the single required ticker parameter, and the schema already documents the NZX ticker format with examples. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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

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

The description states a specific verb+resource ("Get comprehensive board effectiveness dashboard") and enumerates the dashboard's contents (composition, skills heatmap, governance score, benchmarking, succession risk, attendance, remuneration). It is clear what the tool returns, but it never distinguishes itself from the many overlapping siblings (get_board_benchmark, get_board_skills_matrix, get_governance_scorecard, get_succession_plan, get_remuneration_benchmarks), leaving that differentiation to the agent.

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

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

There is no explicit guidance on when to use this tool versus the numerous alternative board/governance tools. "Comprehensive dashboard" hints at an aggregate overview use case, but no condition selects it over get_board_composition_report, get_board_health_score, or the individual component 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful scope context (NZX-only, a fixed bundle of report sections, and a PDF alternative at a given path) but says nothing about auth requirements, rate limits, data freshness, or cost of generating a 'comprehensive' report.

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 tool's identity is front-loaded in the first clause and the content list is a single dense sentence with no filler. The trailing PDF-path note is slightly tangential but is genuinely actionable information rather than padding.

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

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

With one simple string parameter, full schema documentation, an output schema, and read-only annotations, the description is adequate: an agent knows what it gets back and that the call is safe. The main gap is the absence of routing guidance against near-duplicate board tools, which is a usage-guideline concern rather than a completeness one.

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

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

Schema description coverage is 100% and the single ticker parameter is documented with examples ('FPH', 'AIR', 'SPK') directly in the schema. The description adds no syntax, constraint, or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Get a comprehensive Board Gap Intelligence Report for an NZX company' — and enumerates the report's contents (composition, skills gap, director profile, fee benchmarking, governance scores, risk flags). However, it never distinguishes itself from the many similar siblings such as get_board_composition_report, get_board_skills_matrix, get_board_benchmark, or get_board_health_score, which overlap heavily with the listed contents.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named despite ~20 board-related siblings. The content enumeration weakly implies 'use this when you want everything at once' but the agent must infer that itself.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description earns additional credit by disclosing the internal composition of the metric (five factors with sub-components, GRS and fee disclosure under transparency), which tells the agent what the number actually represents. It does not mention cost, latency, or failure 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?

Front-loaded with the verb and resource, then the metric definition, then the usage cue. Every clause carries information (factor names and sub-metrics), so the length is justified rather than padded, though the parenthetical lists make the middle sentence dense.

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

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

An output schema exists, so return values need not be explained, and the description supplies the metric's meaning, scale, and factor breakdown. For a single-parameter read tool this is close to sufficient; the only real gap is the absence of sibling routing among a very crowded governance tool family.

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?

There is a single parameter with 100% schema description coverage, so the schema fully documents the ticker including format examples. The description's "for an NZX company" corroborates the NZX scoping but adds no syntax or constraint detail beyond the schema. Baseline 3 applies when the schema 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?

States a specific verb+resource (board health score) and unpacks what the metric is: a 0-100 composite over five named factor groups. That is far more than a restatement of the name. It stops short of a 5 because it never distinguishes itself from overlapping siblings such as get_board_effectiveness, get_board_skills_matrix, or get_governance_scorecard, which cover some of the same sub-factors.

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

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

"Use when assessing overall board governance quality" gives a general calling condition, so usage is implied rather than absent. However, it offers no exclusions and no routing to the many sibling governance tools, leaving the agent to guess whether this composite or a factor-level tool (e.g. get_board_composition_report) is the right pick.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuinely useful definitional context about what qualifies as 'freed up capacity' and the 12-month window. It says nothing about ordering, pagination, or result size behavior, so it adds only moderate value beyond the annotations.

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

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

Two sentences: the first defines the population, the second states the use case. Front-loaded, zero filler, every clause 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?

With a full output schema and 100%-covered parameters, the description need not explain returns or args, and it covers purpose and scope adequately. The one missing piece is differentiation from the near-identical siblings in the board/director family.

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% — limit, skill, and sector are each documented in the schema with examples. The description adds no parameter-level detail (no default, no combination guidance), so the baseline of 3 applies.

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

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

The description names a specific resource (directors who recently freed up board capacity) and defines its scope precisely — resignations, retirements, reduced workloads, last 12 months. It is clear what the tool returns, but it never distinguishes itself from closely related siblings like search_board_candidates, get_board_vacancies, or get_director_workload.

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 gives one usage context ('identify available director talent for board recruitment'), which is a real when-to-use signal. However, it offers no when-not-to-use and no routing to the obvious alternatives (search_board_candidates, get_board_vacancies), leaving the agent to guess which sibling to pick.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds meaningful context about what the response contains (proficiency per director, gap analysis, diversity score) and framework alignment, but does not note data sources, staleness, or coverage limits. Adequate but not rich beyond the annotations.

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

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

Front-loaded with the core action in the first sentence, followed by the content breakdown and framework note. The 12-category list is somewhat enumeration-heavy but conveys concrete output value rather than padding.

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

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

Output schema exists, so return values needn't be explained, and annotations cover the safety profile. However, given the dense set of adjacent board tools, the description omits the differentiation and scope boundaries an agent needs to select it correctly.

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

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

Schema description coverage is 100%; the single ticker parameter is fully documented with examples ('FPH', 'AIR', 'MEL'). The description adds no further parameter meaning, so the baseline 3 is correct.

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?

Clear specific verb+resource ('Get board skills matrix for an NZX company') and it enumerates the exact output content (12 skill categories, proficiency levels, gap analysis, diversity score). It does not differentiate itself from closely related siblings such as get_board_gap_report, get_board_effectiveness, or get_board_benchmark, so an agent can identify the tool but not easily pick it over neighbors.

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 statement of when to use this tool versus the many overlapping board-analysis siblings, and no exclusions or prerequisites. Usage is only implied by the verb 'Get', which is insufficient against a sibling set packed with board_* 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds genuinely new context: the upstream scraping sources and the dual-mode behavior where supplying vacancy_id switches the result to include candidate matches.

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

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

Three tight sentences that front-load the action and provenance before the optional mode. Every sentence carries information, though the phantom 'remuneration type' filter is 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?

An output schema exists, so return values need no explanation. However, it is unclear how vacancy_id interacts with the other filters (are they applied together or ignored?), and the advertised remuneration filter does not exist, leaving a small but real gap for a 5-parameter 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 the baseline is 3. The description restates the filter dimensions and adds the vacancy_id behavior, but also advertises filtering by 'remuneration type' for which no parameter exists in the schema, a mild inconsistency rather than added clarity.

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

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

States a specific verb and resource ('Get current board vacancies') plus the data provenance (Appoint Better Boards and IoD NZ), which is useful disambiguation. It does not, however, distinguish itself from related siblings such as search_board_candidates or get_board_pipeline, so the agent is left to infer the boundary.

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

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

The description implies usage through its filters and the optional vacancy_id mode, but never states when to reach for this tool over search_board_candidates. There are no exclusions or prerequisites, so an agent must guess at the routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds the nature of the returned content (ratings, targets, forecast distribution, consensus summary), which is useful but not behavioral disclosure beyond annotations. No auth, rate limit, or freshness context is given.

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 front-loaded sentences with the subject (NZX company coverage) established immediately. Slightly list-heavy in enumerating return fields, but nothing is genuinely wasteful.

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

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

An output schema exists, so return values need not be re-explained in the description, and both parameters are documented. Purpose and returned content are adequately conveyed for a simple two-parameter read tool; only usage routing to siblings 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 both the ticker and include parameters are fully documented in the schema, including section values. The description adds no parameter detail, so the baseline 3 applies.

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

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

States a specific verb (get) and resource (analyst/broker coverage) for an NZX company, and enumerates the key data returned. It is clear on its own, but doesn't differentiate itself from overlapping siblings like get_analyst_consensus or get_consensus_estimates.

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 explains what the tool returns but gives no when-to-use guidance, no prerequisites, and does not name alternatives such as get_analyst_consensus or get_consensus_estimates. The agent must infer usage entirely from the name.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful context beyond annotations: the dataset is described as ~11,700 structured events across 131 issuers, and that it includes amounts, pricing, and dilution. This gives an agent a sense of data scope and content without contradicting the annotations.

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

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

Two sentences with no filler. The first sentence states the primary purpose up front, and the second sentence adds valuable detail about event types and dataset scale. Every phrase contributes to understanding the tool.

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

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

With an output schema present and full parameter descriptions in the schema, the description is largely complete for invocation. It clearly identifies the resource and what is included. The only minor gap is that it does not clarify the relationship between the 'buybacks' filter parameter and the 'type=buyback' option, but this is not essential for basic use.

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

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

Schema description coverage is 100%, so the input schema already documents all five parameters including type values, year format, and limit. The description does not add meaning beyond the schema; it mentions event types and pricing information, but these do not clarify parameter formats or relationships.

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

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

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

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

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

The description gives clear context: this is for capital raise history of an NZX company, which implies when it should be used. It does not explicitly name alternative tools or exclusion criteria, but the domain is specific enough that an agent can infer appropriate use.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond that: insider activity window of ±30 days, post-raise return windows of 30/90/180 days, and the composite score classifications. It does not mention auth or rate-limit behavior, but the added analytical scope is substantial.

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, front-loaded with the purpose, then the return contents, then the classification. Every sentence earns its place with no repetition or 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?

Given the existing output schema and annotation coverage, the description provides enough context for correct invocation: it states the analytical purpose, the data windows, and the classification output. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the context filter and its strength/neutral/desperation values. The description does not add parameter syntax or format guidance beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific analysis verb and resource: analyzing capital raises by an NZX company for strength vs desperation. It is clearly distinct from a raw capital-raises listing, but it does not name or explicitly differentiate from the sibling get_capital_raises.

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

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

No when-to-use, when-not-to-use, or alternative-tool guidance is provided. The description explains what the tool returns but not why an agent should choose it over get_capital_raises or other sentiment 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real behavioral substance beyond that: the >10 point LIS gap divergence threshold, the fact that divergence is treated as a governance signal, and that historical trend direction (widening/narrowing) is included in the result.

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

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

Four short sentences, purpose front-loaded, no filler or restatement of the tool name. Dense with substantive detail; a tighter consolidation of the metric list and threshold sentence is the only minor room for improvement.

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

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

For a single-parameter read tool with full annotation coverage and an output schema, this description covers everything an agent needs: what is compared, the interpretation threshold, and the trend content. Return-value detail beyond this is already carried by the output schema.

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 (ticker) and schema description coverage is 100%, so the schema already fully documents it with an example format. The description adds no additional meaning about the ticker beyond what the schema provides, which matches the baseline 3 for schema-carried parameters.

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

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

States a specific verb (get) plus a distinctive resource (Chair vs CEO communication alignment for a company) and enumerates the compared dimensions: LIS, sentiment, conviction, transparency. This is readily separable from adjacent siblings like get_agm_speeches (raw text) or get_disclosure_language (single-entity language 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?

Usage is implied by the governance-signal framing, but there is no explicit 'use this when / use X instead' routing. An agent must infer that this is the comparative counterpart to get_agm_speeches and get_disclosure_language, with no stated prerequisites or 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful scope context beyond the annotations: the analysis is restricted to NZX and to current chairs, plus it enumerates the three output components (chair list, interlock pairs, network metrics).

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

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

Front-loaded with the core purpose, then return contents, then usage triggers in a logical order. The metric enumeration is slightly list-heavy but every clause carries useful information, so it is close to optimally sized.

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

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

With an output schema present, the description need not explain return values, yet it does so helpfully. Combined with annotations covering the safety profile, an agent has enough to call this correctly; the only minor gap is the absence of an explicit alternative tool for director-level networks.

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 tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool applies. No misleading parameter claims are made.

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

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

States a specific verb (Analyze) and a precisely scoped resource (the NZX board chair interlock network), and clarifies the unit of analysis is chairs with multiple board seats. This is distinguishable from adjacent siblings like get_director_network and get_network_intelligence, which cover directors or generic networks rather than chair interlocks.

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?

Explicit trigger phrases ('chair networks, board interlocks among chairs, serial chairs, or how NZX board chairs are connected') tell the agent exactly when this tool applies. It does not, however, name the closest alternative (e.g., get_director_network) and state when to prefer that one instead, so the routing guidance is one-sided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral colour — it enumerates per-requirement status, evidence, recommendations, an overall 0-100 score, and mandatory-reporter status — which tells the agent the shape and depth of the assessment.

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

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

Front-loaded with the framework and scope, then the breakdown, then the use cases — no filler sentences. The enumeration of requirement counts and return fields is dense but each clause carries information; only mild overlap with the output schema.

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?

Covers scope, framework, requirement breakdown, and trigger conditions, and an output schema exists so return values need not be spelled out further. Minor gaps remain around prerequisites (must the ticker be an NZX-listed reporter?) and failure behaviour for non-covered 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?

Only one parameter (ticker) and its schema description coverage is 100%, so the schema already documents it fully with examples. The description adds no ticker-level semantics (e.g. listed-company requirement, invalid-ticker behaviour), 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?

States a specific verb+resource (gap analysis against NZ CS 1-4) plus exact scope: 23 XRB requirements broken into governance/strategy/risk/metrics counts, for an NZX company. This is clearly distinguishable from near neighbours like get_esg_disclosure_gap and get_property_climate_risk without opening the schema.

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

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

The final sentence gives explicit trigger conditions: climate compliance, NZ CS readiness, XRB requirements, TCFD gaps. That is strong positive routing, but it names no exclusions or the sibling tool to choose instead (e.g. ESG disclosure gap) for overlapping 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's only added behavioral context is the NZX scope, which is modest value on top of structured data already present.

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 waste: the capability statement leads and the routing sentence follows. Front-loaded and appropriately sized.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers scope, content, and triggers adequately; the only residual gap is distinguishing this tool from the semantic overlap with sibling committee/board-composition tools.

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 of the four filters (limit, sector, ticker, committee) self-documented including examples and the default/max for limit. The description adds no filter syntax, combination behavior, or default semantics beyond what the schema already states, so baseline 3 applies.

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

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

Specific verb ('Get') plus resource ('board committee membership data') with the returned facets enumerated (chairs, committee types, composition) and the universe named (NZX companies). However, it does not differentiate itself from closely-named siblings such as get_select_committee_activity or get_board_composition_report, so the agent must still infer which one to pick.

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 'Use when user asks about...' sentence gives concrete trigger phrasings (audit committees, remuneration committees, committee chairs, board committee structure), which is genuinely useful routing guidance. It stops short of any when-not or explicit alternative-tool redirection, so it is context without 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?

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely new context by disclosing the data provenance (AI-extracted from filings) and the comparison mechanism (deltas across consecutive extractions), which affects how the agent should interpret 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?

Three tight sentences that front-load the core purpose before elaborating on the compared fields and mechanism. Minor redundancy between 'recent material changes' and 'recent filings', but no wasted padding.

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

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

An output schema exists, so return values need no prose, and annotations carry the safety profile. Given a two-parameter, read-only tool, the description covers source, scope and mechanism adequately; only the when-to-use routing is missing.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents 'days' (default 30, max 365) and 'ticker' (NZX symbol). The description adds no syntax, format or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get recent material changes for a company') and pinpoints the domain: revenue, profit, dividend and guidance deltas from AI-extracted announcement data. The 'compares consecutive announcement extractions' framing differentiates it from static siblings like get_financials or get_dividends, though it does not name any sibling explicitly.

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

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

The description implies a 'recent changes' use case but never says when to choose this over get_announcement_alerts, get_earnings_surprise, get_dividends or get_financials, and gives no exclusions or prerequisites. An agent must infer the routing decision entirely.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world. Beyond that the description discloses ordering ('strongest first'), result-shape limits ('up to 5 source filings per relationship'), what is deliberately not included, and the critical empty-set interpretation. It stops short of any auth, rate-limit or pagination detail, but for this access pattern that is a minor omission.

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 purpose leads and the mode-specific behaviour follows, so it is front-loaded correctly. The long second sentence enumerates relationship types, which is dense but each item is load-bearing for disambiguation from sibling tools; nothing reads as 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?

An output schema exists, so return-value formatting need not be repeated, and the description still covers both invocation modes, exclusions and the empty-result interpretation. What remains unaddressed is pagination or result-size behaviour for the single-ticker mode, which is a small gap for a graph-listing tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: what each parameter combination returns, the ranking of results, and the per-relationship filing cap. That is substantive semantic content beyond 'NZX ticker symbol' and 'Optional second NZX ticker'.

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

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

States a specific verb and resource ('Get recorded connections between NZX companies') and enumerates the exact relationship types covered, each tied to its evidence source. It also carves out scope by excluding related-party transactions and fund holdings, which separates it from siblings like get_hidden_connections, get_corporate_relationships and get_entity_graph without the agent needing to open their schemas.

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

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

The two modes are spelled out clearly: with only ticker you get the links radiating from one company, and with other_ticker you get every link between the pair. It also warns that an empty result means no recorded links rather than no real-world connection, which is a genuine usage caveat. It does not, however, name a specific alternative tool for cases where another connection view is wanted.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result 'can include' optional categories, but it does not clarify default behavior when the include parameter is omitted or explain any other behavioral nuances such as pagination or response size.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description implies that this tool is appropriate when you need broad company detail by ticker, and the 'Can include' phrasing hints at selecting categories. However, it does not explicitly state when to prefer this aggregate tool over the many specialized getter siblings, nor does it mention any exclusions or fallback conditions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the bar is lower. The description still adds meaningful behavioral context: results span current AND historical roles, include company status values (active/struck off/liquidating), and include a computed failure-rate analysis. It does not mention limits, pagination, or what happens for an unknown slug.

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

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

Three dense sentences, front-loaded with the core capability, then coverage detail, then usage triggers. No filler and no repetition of the title.

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

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

With an output schema present, return-value detail need not be restated, and the safety profile is covered by annotations. The description delivers what remains necessary: what data is included, its currency range, and when to reach for this 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 the single slug parameter is already fully documented as a person slug from shared.people. The trailing 'Uses person slug.' restates what the schema says, adding no format, resolution, or error behavior beyond it. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Get full directorship history for any person') and names the data source (NZ Companies Register). It enumerates the scope well (NZX-listed + private, current and historical, status, failure rate). It does not explicitly differentiate itself from close siblings such as get_director_history or get_director_network, which the agent may conflate.

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 trigger conditions ('Use when asked about a person's full board network, private company roles, directorship workload, or company failure history'). No exclusions or named alternatives are given, so the agent still has to infer why this beats get_director_history for a given query.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds useful analytical framing (failure rate, timeline, before/during/after relationship), but since an output schema exists this return-content detail is partially redundant and no auth or scoping caveats are disclosed.

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

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

Three tight sentences, front-loaded with the core action and scope, followed by what is returned. No filler, though the trailing 'Uses person slug' slightly duplicates the schema.

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

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

For a single-parameter read tool with rich annotations and an output schema, the description supplies enough scope and return-content context to call it correctly. Missing only explicit alternative-selection guidance.

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 single slug parameter is fully documented in the schema. The description only restates that it 'uses person slug' without adding format or lookup-source detail, 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?

States a specific verb+resource and clarifies that despite the company-oriented name, this is a person-centric lookup keyed by slug, returning struck-off/liquidated/receivership associations. An agent can distinguish it from company-level tools. It doesn't explicitly contrast with the many adjacent director-risk siblings, keeping it just below a 5.

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

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

Usage is implied (director due-diligence on failure exposure) but there is no explicit when-to-use or when-not guidance, and no alternative tools are named even though siblings like get_prohibited_directors, get_director_risk, and get_financial_distress overlap in scope.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is clear. The description adds the scope of the generated content and an alternative branded PDF endpoint, but does not discuss permissions, rate limits, or other operational behavior beyond what annotations and the output schema provide.

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

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

It is front-loaded with the tool's purpose and contents, then use cases, then the PDF endpoint. The first sentence is dense with enumerations but each item earns its place by scoping the pager; the structure is otherwise efficient and there is no redundant fluff.

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

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

With an output schema present, the description need not explain return values. The annotations cover the safety profile, the schema fully documents the only parameter, and the description supplies content scope, use cases, and an alternative format, making it complete for an agent to call 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% and the single ticker parameter is fully documented as an NZX symbol with examples. The description adds no syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description names a specific verb ('Generate') and a well-defined composite resource ('one-page company snapshot'), then enumerates the exact contents (financial metrics, governance, dividends, insider activity, risk flags, announcements). This lets an agent distinguish it from single-metric siblings like get_financials or get_dividends without opening the schema.

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

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

It explicitly gives three use cases: quick due diligence, adviser client meetings, and company overview summaries. It does not name alternatives or state when not to use it, so it falls just short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description's return-value enumeration (P10–P90, mean, min, max, sector/market-cap breakdowns) largely duplicates the existing output schema rather than adding new behavioral context such as data recency or coverage caveats. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Front-loaded with the core purpose and scope, then returns, then valid values, then usage triggers. The return-value sentence is somewhat redundant given the output schema exists, but the overall structure is tight and every clause is actionable.

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

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

With a complete schema, full annotation coverage, and an output schema, the description needn't explain return shape; it correctly focuses on scope and trigger conditions. The one gap is sibling disambiguation against get_remuneration_benchmarks and get_executive_compensation, which would be valuable in a tool set this crowded.

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

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

Schema description coverage is 100% and every parameter (role, year, sector, market_cap) is documented in the schema itself. The description restates the valid role list and market-cap tiers, which mirrors rather than extends the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Get compensation percentile benchmarking') plus an explicit scope ('across all NZX companies') and a concrete role set, which distinguishes it from a single-company tool like get_executive_compensation. However, it never names or differentiates from its very close sibling get_remuneration_benchmarks, so the agent must infer the boundary.

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

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

The final sentence gives clear triggering contexts ('pay benchmarks, market rates, how much CEOs/CFOs earn, or whether a company overpays vs peers'). There are no when-not conditions and no explicit routing to alternative tools such as get_remuneration_benchmarks or get_executive_compensation, so the guidance stops short of 5.

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