Tizona — Australian business identity tools

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

Annotations already mark the operation as read-only, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: the data source (Fair Work MAPD), the 'verbatim' nature with a CC BY 4.0 license, the exact fields returned (amount, all-purpose flag, payment frequency), and an explicit scope limitation. This is a transparent disclosure of what the tool does and does not do.

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?

Every sentence earns its place: source, input semantics, output fields, licensing, scope boundary, and disclaimer. The most important information is front-loaded and the caveats appear in logical order. There is no fluff or repetition of schema 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 read-only lookup tool with two parameters and no output schema, the description is complete. It explains how to identify the award, what is returned, the distinction between wage and expense allowances, and the important limitation that applicability is not determined. Given the strong annotations and simple parameter set, nothing essential 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?

The input schema already provides complete descriptions and an enum for both parameters, so the baseline is 3. The description adds value by giving concrete examples of valid 'kind' values ('leading hand, first aid, tool' vs 'meal, travel, vehicle') and confirming that the award parameter can be either a code or a fixed id. This layered detail earns 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?

The description clearly identifies the resource ('allowances from the Fair Work Commission MAPD') and the lookup mechanism (award code or fixed id), which makes the purpose immediately understandable. It is not a tautology and does more than restate the tool name. However, it does not explicitly distinguish itself from siblings like award_pay_rate or award_penalties, which keeps it just short of 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?

The description gives strong contextual guidance: which award to use, the kind filter, and a clear statement that this tool only provides dollar values and does not determine applicability. It even advises reading with the award and notes it is not legal advice. It stops short of naming alternative tools or saying 'use this over X', so it gets a 4 rather than 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 mark this as read-only, open-world, and idempotent, and the description adds meaningful behavioral detail beyond them: data is verbatim from FWC, stamped with version/published-year, CC BY 4.0, unknown awards throw, and the result is not legal advice. This is rich context for an agent deciding to call the tool.

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

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

The description is four sentences, front-loads the core purpose, and every sentence earns its place: what is returned, how to filter, provenance/versioning, scope limits, and error behavior. There is no filler or repetition of the title or annotations.

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 there is no output schema, the description fully compensates by describing the return content (base and calculated rates with operative dates), filtering options, data source, licensing, caveats, and the unknown-award error. An agent has enough information to decide when and how to call 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 baseline is 3. The tool description lightly echoes 'award code or fixed id' and 'filtered by classification level or employee-rate-type', but it adds no parameter-level detail beyond what the schema already provides; therefore it does not deserve a higher 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?

The description states a specific operation and resource: returning 'Minimum pay rates for an Australian modern award' from the Fair Work Commission MAPD. It clearly distinguishes the tool from siblings like award_allowances and award_penalties by emphasizing 'Dollar values only' and pay-rate scope.

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

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

It gives clear context on how to invoke the tool (award code or fixed id, optional filters) and explicit exclusions: it does not say which award applies or what is payable, and should be read with the award. It does not name alternative sibling tools directly, so it stops just short of fully explicit 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 mark it read-only and idempotent, and the description adds valuable behavioral context: verbatim FWC output under CC BY 4.0, dollar values only, unknown awards throwing, and a legal-disclaimer caveat. This goes well beyond the structured hints and tells the agent exactly what to expect behaviorally.

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

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

The description is compact yet dense, front-loading the core purpose and then adding only high-value caveats: licensing, scope limitation, legal disclaimer, and error behavior. Every sentence earns its place; there is no filler or redundant restatement.

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 correctly states what the call returns: each penalty's multiplier/percentage and FWC's calculated dollar value. It also covers error behavior, licensing, and the key interpretation boundary, making the tool safe and sufficiently specifiable for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description echoes the award code/fixed id distinction and mentions the optional filtering dimensions, but it does not add deeper semantics beyond what the schema already provides. The example reiterates the schema example without enriching it.

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

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

The description clearly identifies the resource (penalty rates for Australian modern awards), the data source (Fair Work Commission MAPD), and the return content (multiplier/percentage and FWC dollar value). It distinguishes itself from siblings by focusing specifically on penalty rates rather than allowances or pay rates, and by explicitly stating what it does not do.

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: look up by award code or fixed id, optionally filtered by classification or employee-rate-type. It explicitly states a when-not-to-use boundary ('does NOT determine which penalty applies to a shift') and directs the user to read with the award, but it does not name or route to the relevant sibling tool, so it stops short of full alternative 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?

Beyond the read-only/idempotent annotations, the description discloses the one-eleventh calculation rule, exact integer-cent precision, synonym acceptance for basis, and a throw-on-unknown-basis failure mode. This is rich behavioral context that annotations did not provide.

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

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

Three sentences, front-loaded with the core behavior, then the critical rate caveat, then the parameter-specific contract. There is no filler; every sentence contributes operational 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?

For a simple two-parameter calculator with read-only/idempotent annotations, the description covers the main calculation paths and failure behavior. There is no output schema, and the description stops just short of stating the exact return value structure, but the exact-cent language gives enough direction for likely invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by mapping 'exclusive' to add, 'inclusive' to extract, noting synonyms are accepted, and stating that an unknown basis throws instead of returning a wrong figure.

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 first sentence names a precise operation on a specific resource (GST amounts) and distinguishes the two supported modes: add-to-exclusive vs extract-from-inclusive. It also sets it apart from the financial sibling tools by scoping to GST-only arithmetic.

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 clear, actionable conditions: use 'exclusive' when the amount excludes GST and 'inclusive' when it includes GST. It does not name sibling alternatives explicitly, but the decision context is unambiguous enough for an agent to select this tool.

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

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

Beyond the readOnly/idempotent annotations, it adds substantial behavior: FREE, observational datacenter vantage, not guaranteed, unknown URLs return unknown and schedule themselves, and it reports published price plus user-agent variation. No contradiction with annotations.

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

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

The description is compact, front-loads the use case, and each sentence carries distinct information: free, purpose, result details, unknown behavior, bulk alternative, and limitation.

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 tool with no output schema, the description covers input context, expected outcome categories, unknown handling, pricing/UA nuance, and reliability caveat. An agent has enough to select and invoke it correctly.

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

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

Schema coverage is 100% and there is only one simple parameter whose schema description already explains the URL. The tool description adds situational context but not new semantic detail about the parameter, 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?

Description states a specific action: before fetching a URL, check whether crawler identity will be served, refused, or met with a paid tollgate. It names the resource (URL/crawler-access posture) and explicitly distinguishes itself from the bulk sibling triage_ai_crawler_access.

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?

Tells the agent when to invoke it ('Before fetching a URL') and points to the bulk alternative ('Bulk: triage_ai_crawler_access'). The 'not a guarantee' caveat also sets expectations for relying on the result.

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, covering safety. The description adds rich behavioral detail beyond that: it knows 81 spellings of 30 legal forms across 21 countries, ignores word order, down-weights generic words, and flags obfuscation (homoglyphs, invisible characters, digit substitution) in an 'obfuscation' field. It also mentions the reasoning is broken out, giving insight into the output structure. This fully compensates for the missing output schema.

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

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

The description is a single, information-dense paragraph. It is front-loaded with the core purpose, then enumerates specific behaviors, and ends with an important interpretive note. Every sentence adds unique value, but it is longer than strictly necessary. It could be tightened, but the structure is logical and efficient.

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

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

Given there is no output schema, the description compensates well by indicating output components: a score from 0 to 1, broken-out reasoning, an obfuscation field, and an instruction to check distinctiveness. It also provides an example in the schema. An agent has enough information to call the tool and interpret results. The tool is simple (3 params, 2 required, read-only) so this level of detail is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The main description adds context that helps understand how parameters are interpreted: it explains that legal forms like 'Pty. Ltd.' and 'Proprietary Limited' are treated equivalently, and that word order is ignored. This goes beyond the terse property descriptions ('First name.', 'Second name.', 'Defaults to company.') and helps an agent input names correctly. It doesn't directly describe the 'type' parameter, but the example shows company usage. Slight extra value over 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 opens with a precise verb and resource: 'Score whether two names are the same entity, 0 to 1, with the reasoning broken out.' This clearly distinguishes it from sibling tools like match_entity_name (boolean match) and normalise_entity_name (transformation), even without naming them. The scope is unambiguous.

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

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

The description gives a specific interpretive guideline: 'Check distinctiveness: names of only generic words identify weakly however well they match.' This helps an agent decide when to rely on the score. It doesn't explicitly state when to prefer this tool over siblings, but the purpose is clear enough that an agent can infer it. Slightly better than average but not explicit about 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?

Beyond the annotations, the description reveals the algorithmic approach ('grouped by distinctive words'), the output signal (comparison count), and the truncation failure mode with a retry instruction. This is substantive behavioral disclosure that helps the agent anticipate edge cases.

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 with no filler. The opening sentence establishes purpose, the second gives algorithmic context, and the third provides a critical edge-case instruction. 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?

The description covers purpose, scale limit, algorithm, output signals, and retry guidance, which is strong for a tool with no output schema. It leaves some ambiguity about the exact shape of returned groups and how `type` changes matching, but the essential operational information is present.

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 only 33%, and the description does not compensate by explaining the `type` or `threshold` parameters. It mentions the 250-name limit, which is already in the schema, but gives no guidance on how person/company selection or threshold values affect clustering behavior.

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 action ('Cluster up to 250 names into groups that are the same entity') with a clear resource and outcome. It also sets it apart from sibling tools by emphasizing batch clustering rather than pairwise comparison or normalization.

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

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

It provides concrete contexts such as CRM merge or supplier-list cleanup, and implies when the tool is appropriate via 'not compared exhaustively.' It stops short of explicitly naming sibling alternatives like compare_entity_names or match_entity_name, so it earns 4 rather than 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 mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: threshold filtering, ranking, index tagging, legal-form/word-order/obfuscation awareness, and a throw-over-truncate failure mode on oversized inputs. This is valuable and non-redundant.

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 compact sentences with no filler. The main behavior is front-loaded, the relationship to compare_entity_names is given in one clause, and the important error behavior is stated last. Every sentence earns its place.

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

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

With no output schema, the description responsibly sketches the output shape: filtered, ranked, indexed results. It also discloses the cardinality limit and failure behavior. It could be slightly more explicit about the return structure (e.g., whether scores are included alongside names), but the description is largely sufficient for an agent to understand and invoke the tool.

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

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

Schema description coverage is 80%, so the parameters are mostly self-documenting. The description adds minimal parameter-specific meaning: 'up to 750 candidates' echoes the maxItems constraint, and 'threshold' echoes the schema's threshold property. It does not materially deepen understanding of query, candidates, type, or limit.

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: score one name against up to 750 candidates, returning those over the threshold ranked and tagged with their index. It also distinguishes this from the sibling compare_entity_names by characterizing it as that comparison applied as a search.

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 tool clearly signals a one-to-many search use case: one query name versus a candidate list. It references the related compare_entity_names tool and states a hard boundary—over 750 candidates throws rather than truncates—so an agent knows not to use it beyond that limit. However, it does not explicitly enumerate when to prefer it over other siblings like deduplicate_entity_names.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral detail beyond those: outputs a stable/semantic grouping key, 'reports every token removed', and 'flags' obfuscation such as homoglyphs and invisible characters. 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 sentences with no filler: the core transform, its deterministic nature, the report/flag output, and the relationship to sibling tools are all packed in efficiently. The most important behavior is front-loaded before the output details.

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

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

For a read-only, idempotent transform with two simple parameters, the description plus schema cover the essential calling intent. The main gaps are the unexplained `type` parameter and lack of explicit output shape, but the report/flag language gives enough expectation for an agent.

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

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

Schema coverage is 50% because `type` lacks a description beyond its enum values. The description does not explain what `type` does (company vs. person) or how it affects legal-form splitting, nor does it compensate by describing parameter interaction. The only parameter gloss comes from the schema's one-line `name` description.

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

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

The description uses a specific verb and resource: 'Reduce a name to its comparable core with the legal form split out'. It also distinguishes itself from siblings by stating it exposes 'the normalisation the matching tools apply, on its own', making it clear this is the standalone transform versus match/compare/deduplicate tools.

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

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

The description clearly situates the tool as the normalisation layer beneath the matching tools, giving an agent context on where it fits. It implies use this when you need the grouping key or the removal/obfuscation report directly, though it does not explicitly list exclusions or name specific alternative 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?

Beyond annotations, it discloses that this is a stateful operation ('since your last pull'), that unchanged URLs return nothing, that the first pull reports the starting state, and that every pull spends one credit regardless of results. These are meaningful behavioral traits not visible in the schema or 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 core operation and condition, followed by essential stateful and cost behavior. No filler or repetition that does not earn 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 one parameter, no output schema, and minimal annotations, the description covers the key operational facts: what is returned, what is omitted, initial state behavior, and per-call cost. An agent has enough 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?

Schema coverage is 100%, with the watchId parameter already documented as returned by watch_ai_crawler_access. The description repeats that provenance but adds no new syntax, format, or constraint details beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('returns') and the specific resource: URLs whose access changed since the last pull, with concrete examples of change types. It also references its companion tool watch_ai_crawler_access, distinguishing this incremental pull from the one-off check/triage siblings.

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 ties usage to a watchId obtained from watch_ai_crawler_access and explains first-pull behavior and credit cost, giving clear context for when to call it. It does not explicitly state exclusions or alternatives, but the workflow implication is strong.

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 the safe read profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds substantial context beyond that: the exact-to-the-cent accuracy guarantee, the list of returned fields, the method-change rationale (Payday Super), the ATO sourcing caveat and non-advice disclaimer, and the throw-on-out-of-range-date behavior. This is genuinely informative and consistent with the annotations — no contradiction.

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 opening sentence, followed by returns, then the critical method caveat, then scope constraints. It is on the longer side, but every sentence carries distinct information — the Payday Super warning, the qualifying-earnings boundary, and the date constraint all earn their place. No filler or tautology.

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

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

Despite lacking an output schema, the description compensates by enumerating the return values (SG, rate, capped earnings, financial year). It also covers accuracy, temporal scope, error behavior, and legal caveat — everything an agent needs to invoke and interpret the tool correctly. No output schema or sibling routing gaps remain.

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 parameters are already documented (qualifyingEarnings amount with example; asAt format and default). The description contributes one useful caveat — that the tool does NOT define what counts as qualifying earnings and trusts the supplied figure — which clarifies the parameter's scope. Otherwise it mostly restates schema content, matching the baseline for full 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?

States a specific verb (compute), a specific resource (Australian Superannuation Guarantee), and the exact input basis (qualifying-earnings amount). The precision guarantee ('exact to the cent') and distinct domain clearly separate it from all siblings, which concern awards, GST, entity names, email verification, and crawler access — none overlap with SG calculation.

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 strong temporal context: the tool computes the current way (post-1 July 2026 Payday Super basis) and explicitly warns that old quarterly-OTE code is now wrong, so an agent knows not to reach for legacy methods. It also scopes usage to 'Current financial year only; an out-of-range date throws.' It names no sibling alternative, but none of the listed siblings is a relevant SG fallback, so this is a minor gap rather than a routing omission.

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 convey a safe read-only, idempotent operation. The description adds valuable behavioral details beyond that: results are in integer cents, both rounding totals and their exact discrepancy are reported, malformed lines throw, and mixing rounding methods is prohibited. No annotation contradiction exists.

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

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

A single front-loaded sentence states the core operation immediately and earns its length by adding constraints and failure behavior with no filler.

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

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

There is no output schema, but the description names the key output qualities (integer cents, discrepancy) and failure behavior, and the input schema fully covers parameters. It stops short of specifying the exact return shape/field names, which would make it fully complete.

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

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

Schema description coverage is 100%, so the schema already documents lines, rounding, and taxInclusive. The description adds the GST-free and rounding-method context but does not add parameter-level details; with the schema carrying the full burden, a baseline 3 is appropriate.

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

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

The description uses a specific verb ('Total'), names the resource (multi-line invoice), and states the scope (handles GST-free lines, ATO rounding methods, discrepancy reporting). It clearly distinguishes this from sibling GST/payroll tools by focusing on invoice total computation rather than allowances or GST calculation.

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 main use case and imposes a constraint ('an invoice must not mix them'), but it does not explicitly state when to prefer this tool over the sibling calculate_gst or other related tools, and offers no 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds significant behavioral context: it warns that results are 'observational' and 'not a guarantee', clarifies that 'a user-agent is a claim, not a credential', and discloses cost implications (unknown URLs free, known URLs metered). This goes well beyond annotations and prepares the agent for the tool's limitations.

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, dense sentence that front-loads the core purpose and then compactly adds cost, observational nature, and an important caveat. Every clause earns its place—there is no filler or redundancy. It is concise yet information-rich.

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

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

For a tool with one parameter, full schema coverage, and annotations covering safety, the description provides the essential context: what it does, how it behaves (observational/caveats), and cost implications. It does not specify the exact output format, but given no output schema, it should at least hint at what the summary contains—which it does ('summary to branch on'). This is sufficient for an agent 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 single 'urls' parameter has a description that already covers limits (up to 200) and protocol (http or https). The tool description doesn't add meaning beyond the schema for this parameter; it only reinforces what is already structured. Since the schema handles the load, baseline 3 is appropriate.

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

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

The description clearly states a specific action: 'Check up to 200 URLs in one call for AI-crawler access', and details the three categories of outcomes (readable, refuse, paid tollgate). It distinguishes itself from siblings by its batch size and summary output, making its purpose unambiguous and differentiating it from tools like check_ai_crawler_access or verify_ai_crawler.

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

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

The description provides when-to-use guidance by stating 'with a summary to branch on before spending a fetch' and explains cost behavior for unknown vs known URLs. This implies it's a pre-flight triage step, though it doesn't explicitly name alternative tools or exclusion conditions. The context is clear enough for an agent to select it appropriately among siblings.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral detail: whitespace and hyphens are ignored, BSB has no check digit, unknown schemes throw, and ABN validation also flags company status. It fully discloses the tool's limits and edge cases.

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 cover the core operation, key edge cases, and limitations without repetition. Important information is front-loaded, and every sentence earns its place.

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

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

Despite having no output schema, the description conveys the essential outcome (pass/fail), the ABN company flag, the BSB format-only behavior, and the throw condition. It stops short of specifying the exact return shape, but an agent has enough to invoke the tool correctly.

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

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

The schema already documents both parameters at 100% coverage, including the enum for type and the note that spaces and hyphens are ignored. The description adds some useful context, such as BSB being format-only, but most parameter meaning is already in 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: 'Validate an Australian ABN, ACN, ARBN, TFN, Medicare or BSB against its official checksum.' It names the exact identifier types and the core operation, making it easy to distinguish from sibling tools like verify_email_address or match_entity_name.

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 and important exclusions: it is offline and deterministic, and a pass does NOT prove an identifier is issued, active, or held by anyone. This tells the agent when not to rely on the tool, though it does not explicitly name alternative sibling tools.

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

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

Annotations already indicate a read-only, idempotent, non-destructive tool, and the description adds substantial behavioral detail beyond that: proof-of-key control rather than network origin, the operator key-directory fetch, the IP-range check, and the four possible return statuses. It also explicitly avoids false positives on spoofing, which is valuable operational context.

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

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

The description is longer than average but every sentence contributes: cost, purpose, both verification methods, required inputs, supported operators, return statuses, and a key caveat. It is well-labelled and front-loads the core purpose before detail.

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

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

For a tool with seven optional parameters, no required fields, and no output schema, the description provides enough to invoke it correctly: the two mutually relevant input combinations, the meaning of each verification mode, and the return status vocabulary. It covers both invocation modes and the tool's limitations.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by grouping parameters into the two verification flows: signatureInput/signatureAgent/url for cryptographic, and ip/userAgent/claimed for network. This clarifies how the parameters work together beyond individual schema entries.

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 precise verb and resource: verify whether a crawler is who it claims to be, via cryptographic or network-range evidence. It distinguishes itself from sibling access-focused tools and clearly names the two verification modes. The phrase 'never calls a claim spoofed when it merely cannot be checked' adds a clear behavioral 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 gives explicit input-selection guidance: use cryptographic verification when a Web Bot Auth signature is available, and network verification when only an IP/user-agent is available. It does not explicitly name alternative sibling tools or state when not to use this tool, but the context for invocation is clear.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior, and the description adds substantial behavioral detail beyond that: no mail sent, no SMTP probe, live MX DNS lookup, provider naming, and the explicit caveat that domain reachability is confirmed but not mailbox existence. It also enumerates exact verdict values and output components, providing rich transparency for an agent.

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 dense yet well-structured, front-loading the primary use case ('Validate an email before spending a send, token, or signup') and then systematically listing checks, outputs, and limitations. Every clause contributes useful information, and there is no filler or repetition of schema fields.

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

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

Despite having no output schema, the description fully enumerates the return values: verdict, 0-100 score, canonical mailbox, and verdict hash, including all possible verdict strings. It also clarifies the critical limitation that mailbox existence is not confirmed. For a single-parameter tool with read-only annotations, this is complete enough for an agent to select and 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?

The input schema already fully documents the single `email` parameter with a description and maxLength, giving 100% schema coverage. The tool description adds helpful context about validation behavior, but does not add new meaning specific to the `email` parameter beyond what the schema states. This meets the baseline but does not exceed it.

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

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

The description opens with a clear verb and resource: 'Validate an email' before a send, token, or signup. It then enumerates exactly what checks are performed (RFC-5322 syntax, MX, disposable domains, role mailboxes, typos) and what the tool returns, making its purpose unmistakable. Although siblings are mostly unrelated, the description strongly differentiates the tool by stating it sends no mail and does not confirm mailbox existence.

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

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

The description clearly states when to use the tool: before spending a send, token, or signup, and without sending mail or probing SMTP. It does not explicitly name alternatives or exclusions, but given the sibling list is largely unrelated, this is sufficient context. The phrase 'FREE' also signals that cost is not a concern for this validation step.

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 a non-read-only, non-idempotent write, and the description adds useful lifecycle details: the returned watchId is a secret bearer token, pulls are paid, adds are free, and the watch expires after inactivity. This goes beyond the annotations, though it doesn't specify how long inactivity is or what happens to unused credits.

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

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

Three sentences, with the core action first, the token-handling warning second, and lifecycle/pricing last. The metaphors ('census', 'tollgate', 'identity refused') add color but are not strictly necessary; still, no sentence 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?

For a 3-parameter tool with no output schema, the description covers the essential return value (watchId), the security requirement, and the next workflow step (pull_ai_crawler_watch). It doesn't describe error cases or the exact response shape, but an agent has enough context 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?

With 100% schema description coverage, the baseline is 3. The description reinforces that credits are pre-bought for pulls and that URLs are registered, but it doesn't add meaningfully to the freshness parameter beyond what the schema already provides.

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

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

The description uses a specific action ('Register a set of URLs and pre-buy pull credits') and clearly states the resource being watched (crawler access changes) and the output (a watchId). It distinguishes itself from pull_ai_crawler_watch by framing this as the registration step and that as the retrieval step.

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

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

It explicitly names pull_ai_crawler_watch as the companion tool to use for pulling changes, and the watch/expiry/pricing language conveys an ongoing-monitoring context. It doesn't explicitly contrast with one-off check/triage siblings such as check_ai_crawler_access, so it is clear but not exhaustive.

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