Legis-Link

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 main added value is disclosing the return payload: calculated value with units, method/formula, derating or correction factors, and governing code reference. The '[PRO]' prefix signals a paid/authenticated tier, though the description never states that an api_key parameter is required or what happens without it.

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 the when-to-use clause are front-loaded, then return behavior, then capability list, then examples — a logical progression with no filler. The 'and more' capability sentence and the long example list are slightly padded but each still carries routing value.

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

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

With no output schema, the description correctly compensates by describing the return contents. It covers trades, units, and jurisdictions, but omits the Pro API key prerequisite that the schema reveals — a material gap for an agent that would otherwise fail the call.

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; the description earns above that by giving three concrete example inputs that model how to populate the free-text 'calculation' parameter. It does not add anything about 'role' or 'region' beyond the schema, which keeps it from a 5.

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

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

States a specific verb ('performs numerical technical calculations') plus the domain (construction trades) and explicitly separates itself from the nearest sibling by saying 'not just checked for compliance', which points at check_compliance. An agent can distinguish it from all seven siblings without opening a schema.

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

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

'Use this tool when a specific measurement, size, rating, or capacity needs to be calculated — not just checked for compliance' gives an explicit when-to-use plus an implicit exclusion routing compliance checks elsewhere. The enumerated capability list and three worked example inputs further anchor invocation.

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 mutability are covered. The description adds real value by disclosing the three-value return status and that answers include precise standard citations plus caveats. It does not mention the free-tier 50 requests/day limit or that results may be REQUIRES_VERIFICATION rather than definitive - but the rate limit lives in the schema.

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

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

Front-loaded with purpose, then trigger, then return shape, then exclusions - a logical order an agent can scan. The trade/region coverage sentence is long but earns its place by bounding scope; the whole is slightly dense but free of 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?

With no output schema, the description carries the return-value burden and does so explicitly (status + standard + caveats). Combined with 100% schema coverage on all five parameters and a full annotation set, an agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description adds genuinely additive scope information: it names the supported trades and the supported jurisdictions ('Australia, UK, USA, Canada, and EU'), which constrains the free-text region parameter that the schema only illustrates with examples.

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 ('answers construction trade compliance questions with exact code references and clause citations') and enumerates the trades and jurisdictions covered. The output vocabulary (COMPLIANT, NON_COMPLIANT, REQUIRES_VERIFICATION) makes it immediately distinguishable from siblings like get_code_reference or verify_material_compliance.

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 both the trigger condition ('when a tradesperson or engineer asks whether a specific installation, practice, or configuration is compliant') and explicit exclusions naming the alternatives to use instead (calculate_technical_spec for calculations, plus safety checklists and RAMS documents). Nothing 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?

Goes well beyond the readOnly/idempotent annotations by disclosing output size (800-1500 words, longer than other tools), exact document structure, print/site-file formatting intent, and that the region drives which WHS/CDM/OSHA legislation is cited. The [PRO] marker signals the api_key gating requirement. Nothing here contradicts the readOnlyHint, since generation has no side effects.

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

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

Front-loaded with the artifact definition, then use-case, then output structure, then examples — a logical order an agent can parse quickly. The three example tasks add length but each demonstrates a different trade/region pairing, so they earn their place; the section enumeration is slightly verbose but maps directly to the return value.

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

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

There is no output schema, and the description fully compensates by describing the three output sections and expected length. Combined with 100% schema coverage on the 7 parameters, an agent has everything needed to decide to call it and to construct correct arguments.

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 signal by giving three concrete example task strings that illustrate the expected granularity for the `task` parameter and the region/trade combination. It also implicitly reinforces that region must not be assumed, matching the schema's explicit warning.

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 artifact: 'Generates a complete Risk Assessment and Method Statement (RAMS) document', and even maps the artifact to regional names (JHA, SWMS). The enumerated output sections (Hazard Register, Method Statement, Qualifications) make it unmistakably distinct from siblings like generate_safety_checklist or check_compliance.

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 trigger condition: 'Use this tool when a foreman or PM needs a formal safety document before a high-risk task.' The regional-jurisdiction note further narrows appropriate use. It stops short of naming when NOT to use it or pointing to the sibling checklist/compliance tools for lighter-weight needs.

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 adds genuine context beyond that: the per-item output structure and the citation standards used (WHS Act 2011, CDM 2015, OSHA 29 CFR 1926). It does not mention the Pro API key requirement or any rate/usage constraints in prose, which keeps it just short of 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?

Four sentences, front-loaded with purpose then usage, exclusions, and examples; nothing is padding. The example task list partially overlaps with the `task` parameter's own schema example, which is a small redundancy rather than a defect.

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?

There is no output schema, yet the description compensates by describing the shape of each returned item (requirement, control measure, mandating regulation). Combined with explicit when/when-not guidance and sibling routing, an agent has everything needed to select and 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 description coverage is 100%, so the baseline is 3. The description's 'Example tasks' list adds calibration value for the `task` parameter—showing the expected specificity (activity + hazard context)—and the citation examples signal how `region` drives output. It does not add anything about `role` or the api_key beyond the schema.

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

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

The description states a specific verb and resource ('Generates a numbered safety checklist') and enumerates the output contents: PPE requirements, hazard controls, and regulatory citations per item. It also names what it is not ('full RAMS document') and points at the sibling that handles that, so an agent can distinguish it from generate_rams and get_inspection_requirements without opening a schema.

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

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

It gives an explicit when-to-use trigger ('when a foreman or safety officer needs a task-specific checklist before work begins'), an explicit when-not ('Do NOT use this tool to generate a full RAMS document') with the named alternative, and three worked task examples that show the intended granularity.

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; the description goes further by spelling out the return payload (standard name, edition year, clause/table, plain-English summary) and warning not to assume a default jurisdiction. That is value the annotations cannot convey.

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 and the routing exclusion are front-loaded, and examples are compact and illustrative. The sentence about pre-populating compliance documents, RAMS, or certificates is mildly redundant with the earlier use-case framing but still earns its place by signalling downstream workflow.

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?

There is no output schema, so the description carries the return-value burden and does so explicitly. Combined with the region/jurisdiction caveat and worked examples, an agent has everything needed to invoke this correctly for a 4-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%, including enum values for trade and explicit guidance on region and the free-tier api_key, so the baseline is 3. The description reinforces region's role in edition selection but adds no syntax or constraint 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 concrete verb ("Retrieves") and concrete resources (code sections, standards, regulatory references) scoped to a construction trade topic. It also distinguishes itself from the compliance-checking sibling by framing itself as a citation lookup rather than a yes/no verdict.

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 an explicit when-to-use ("when you need to cite the exact standard document, clause number, table reference") and an explicit exclusion ("without asking a yes/no compliance question"), which implicitly routes compliance verdicts to check_compliance. It adds downstream use cases (RAMS, certificates, compliance documents) and three concrete example 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value beyond that by describing the return payload (numbered inspection stages with inspector role, certificate type/form number, regulatory reference, notification timing) and the practical motivation (avoiding rework), though it says nothing about API-key failures or rate limits.

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

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

Front-loaded with the core purpose, then usage trigger, return shape, and examples — every sentence contributes. The example list at the end is slightly redundant with the schema's own installation example, costing a point.

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 no output schema, the description correctly carries the burden of describing the return value in useful detail. For a Pro-gated, jurisdiction-dependent lookup it is nearly complete, missing only failure/auth behavior details.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaning by demonstrating how trade, region, and installation combine ('residential electrical installation NSW', 'gas fitting domestic kitchen UK') and by stressing jurisdiction variance. It does not explain the role enum or the api_key requirement beyond the schema, keeping it at a 4.

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 (returns mandatory inspection hold points, sign-off authorities, certificates, and notification requirements) with clear scope limited to a jurisdiction/installation. It is distinguishable from siblings like check_compliance and get_code_reference because it is framed around inspection stages and stop-work points rather than general code or compliance checks.

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 frames the usage scenario ('when a foreman or PM needs to know who must inspect, at what stage work must stop...') and gives example installation queries. It does not name alternatives such as check_compliance or get_code_reference or state when NOT to use it, 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, non-destructive, and closed-world, so safety is covered. The description adds valuable return-shape context (countries, sub-regions, primary standards), which annotations cannot express; it stops short of noting rate limits, though the api_key schema covers the free-tier cap.

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 action, then usage guidance, then return shape. No filler; every sentence contributes.

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?

There is no output schema, and the description compensates by describing the returned structure (countries, sub-regions, applicable standards). Combined with complete schema parameter docs and full annotations, 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% and the trade enum is fully documented in the schema, so the schema already does the heavy lifting. The description only restates that the list is scoped 'for a specific trade' without adding format or filtering semantics beyond what the schema provides.

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

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

The description uses a specific verb ('Lists') and precise resource ('all jurisdictions and regions supported by Legis-Link'), scoped by trade. It is clearly a discovery/lookup tool, distinguishable from its siblings (check_compliance, calculate_technical_spec, etc.) which are action-oriented.

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 explicit sequencing guidance: 'Use this tool before calling other tools to confirm that the target region is supported,' and names the fallback condition 'when the user has not specified one.' An agent knows both when to call it and why.

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), and the description goes further by declaring the three possible verdicts and that a governing clause and compliant alternative are returned — important because there is no output schema. It does not mention the Pro API key/prerequisite in prose, leaving that to the schema's api_key description.

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 statement is front-loaded, followed by return values, then routing guidance, then examples — a sensible order. Slightly padded by the '[PRO]' tag and three examples where two would likely suffice, but nothing is genuinely 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 no output schema, the description compensates by describing the three return verdicts and the governing clause plus compliant alternative, which is what an agent needs to interpret results. It lacks any note on the Pro API key requirement or failure modes, but the schema covers the key.

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

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

Schema coverage is 100%, so the schema carries most semantics (baseline 3). The description adds value by showing via example inputs how trade, region, material specification, and use case combine into a single realistic query (e.g. '2.5mm2 TPS cable for 20A underground direct burial circuit NSW').

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 (checks a material/product/component against code requirements for a trade and jurisdiction) and explicitly names the sibling it is not (check_compliance). The enumerated return states plus the compliant-alternative output make the tool's job unmistakable.

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 an explicit when-to-use ('BEFORE ordering materials to avoid costly substitutions on site') and an explicit when-not-to-use with the correct alternative ('Do NOT use this tool for general compliance questions — use check_compliance instead'). Three worked example inputs demonstrate the expected query granularity.

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