itsmyship Agent Tools

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

With no annotations, the description carries the full behavioral burden, and it does disclose useful traits: incidental holiday skipping, a statutory section citation, and the exclusive start-date convention. It omits error behavior for invalid rules, handling of the jurisdiction default and region, and whether results are deterministic.

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 action and scoping, and each sentence adds distinct information (scope, return values, counting convention). No 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 did not need restating, yet the description is thin for a 5-parameter tool with zero schema documentation. The opaque required 'rule' parameter and the region/jurisdiction inputs are unexplained, leaving real gaps for correct 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 description coverage is 0% across 5 parameters, so the description must compensate. It partially does: 'add (or subtract)' implies negative days values and 'the start date is not counted' defines exclusive counting for start_date, but it says nothing about rule, region, or jurisdiction 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 (add/subtract) plus resource (working days) and scopes it to a NZ statute's definition, which cleanly separates it from count_working_days and nz_holidays. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.

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 guidance on when to use this versus count_working_days or list_rules, and no prerequisites (e.g. that a valid rule from list_rules is required). Usage is only implied by the verb semantics.

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

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

With no annotations the description carries the full burden, and it does disclose one genuinely useful behavioral detail: the counting boundary is exclusive of from_date and inclusive of to_date, which pre-empts off-by-one errors. It omits everything else an agent needs — rule resolution, how region/jurisdiction alter the result, the NZ default, and error 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?

A single tight sentence with the counting window front-loaded and zero filler. The phrasing 'after from_date up to and including to_date' is slightly awkward but is the most information-dense part of the definition.

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, but for a five-parameter tool with no annotations and 0% schema coverage the definition is thin. An agent cannot tell which rule values are legal or how region/jurisdiction affect the count without trial and error.

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

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

Schema description coverage is 0% across five parameters, so the description must compensate and mostly does not. It names from_date, to_date and rule but adds no format, expected values, or meaning for region and jurisdiction, and gives no hint about valid rule identifiers.

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 ('Count working days') plus the counting window, which cleanly separates it from the sibling add_working_days. However, it never explains what a 'rule' is or how this differs from the other date/holiday siblings like list_rules or nz_holidays.

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 or when-not-to-use guidance, and no mention of alternatives despite four plausible sibling tools. The phrase 'under a rule' implies a required rule input but never says how to obtain a valid rule (e.g., via list_rules) or what happens if the rule is unknown.

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

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

No annotations are provided, so the description carries the full behavioral burden. It only enumerates what the list contains (section reference, text, version); it says nothing about read-only nature, jurisdiction behavior, ordering, pagination, or volume of 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?

A single front-loaded sentence with no filler, and the returned fields are listed compactly. It is appropriately sized, though it spends words on return contents that the output schema already covers.

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 needn't be re-explained, but the description leaves the one input parameter entirely unaddressed and gives no usage context for a tool sitting among several similarly named sibling rule/date utilities. Incomplete for the agent's decision needs.

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 0% for the single `jurisdiction` parameter, which carries only a default of "NZ" and no description. The tool description never mentions jurisdiction at all, so it does not compensate for the schema gap; an agent cannot tell what values are valid or whether the default is overridable.

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 clear verb ("List") and resource ("working-day rules") plus the payload fields returned. It is distinguishable from siblings like add_working_days and count_working_days, though it never explicitly names what it is not, so it falls short of the top band.

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 prerequisites, and no routing to alternatives. An agent gets no signal about when list_rules is preferable to nz_holidays or the count/add variants.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses that both actual and observed dates are returned and that provincial anniversary days are included, plus the supported year window. It does not explicitly state the operation is a read-only lookup or say anything about permission needs, but for an obvious query tool the remaining gap is modest.

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 resource and scope front-loaded and the optional parameter example trailing. No filler, no repetition of the tool name.

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. However, for a 3-parameter tool with zero schema description coverage, the unaddressed 'jurisdiction' parameter and the total absence of usage routing against the working-day siblings leave meaningful gaps.

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 0%, so the description must compensate. It does document the year range (2020-2030) and gives an example region value ('wellington'), which the schema lacks, but the 'jurisdiction' parameter (default 'NZ') is never mentioned or explained, leaving a third of the parameters undocumented.

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 (NZ public holidays, actual and observed, plus provincial anniversary days) and a clear scope (a given year, 2020-2030). It is easily distinguished from the validate_* and count_working_days siblings, though it never explicitly contrasts itself with 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?

There is no statement of when to use this tool versus siblings like count_working_days or add_working_days, and no prerequisites or exclusions. The only guidance-like content is the valid year range, which is really a parameter constraint.

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

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

With no annotations, the description carries the full behavioral burden. It does usefully disclose that this is a pure checksum/algorithm check (not a live registry lookup) and that it is free, which tells the agent there is no auth or cost concern. However, it says nothing about failure behavior, error signalling, or scope 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?

One short sentence with the key fact ('Free') front-loaded and no filler. It is efficient, though the brevity comes at the cost of the missing detail noted in other dimensions.

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 described. For a simple two-parameter validator the description is minimally sufficient, but with zero annotation coverage and zero parameter description coverage it leaves the input contract under-specified.

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 0% across two parameters. The description mentions the ABN concept but gives no format guidance (e.g., 11 digits, spacing, string vs numeric) and never explains the 'jurisdiction' parameter or why it defaults to AU for an Australia-specific check.

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 ('check') and resource ('an Australian Business Number's checksum'), plus the algorithm used (ABR). The 'Australian' qualifier implicitly separates it from siblings like validate_ird and validate_nz_bank, though no sibling is named 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?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no mention of what a caller should do when validation fails. The only contextual hint is the 'Free:' prefix, which signals a cost model rather than usage guidance.

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

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

With no annotations, the description still discloses three non-obvious traits: the tool is free (no auth/cost), it implements Inland Revenue's written steps rather than IRD's published Example 3, and it deliberately reports 150000026 as invalid. That last point is genuinely useful behavioral context an agent could not infer from the schema, though input-format expectations and error behavior 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?

A single front-loaded sentence leads with the action and scope, and the parenthetical carries real information rather than filler. It is slightly dense and the trailing caveat is a touch cryptic, but nothing 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?

An output schema exists, so return values need not be explained, and the algorithm source is given. However, the undefined 'jurisdiction' parameter, unspecified input format, and the ambiguous phrasing 'is reported invalid' (by whom?) leave gaps for a two-parameter validation 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 0%, so the description must carry parameter meaning and it largely does not. It implies what 'number' is but never states format or length constraints, and the 'jurisdiction' parameter (default 'NZ') is not mentioned at all, leaving a caller unaware it can be set.

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 (check/validate) and resource (an NZ IRD number's check digit), and the 'NZ IRD' scope cleanly separates it from the sibling validators validate_abn (Australian) and validate_nz_bank (NZ bank accounts). An agent can route to it without opening any 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?

Usage is only implied by the name and the 'NZ IRD' qualifier; there is no explicit when-to-use, when-not-to-use, or named-alternative guidance. The sibling set makes the routing fairly obvious, but nothing in the text tells the agent when this tool is the wrong choice.

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

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

With no annotations, the description carries the full disclosure burden and does well: it declares the cost tier, names the algorithm, and explicitly states what is NOT verified (branch against the Payments NZ register). It omits auth/rate-limit behavior, but the key correctness caveat is disclosed up front.

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 no filler; the scope limitation is front-loaded immediately after the purpose statement. Every clause carries information an agent needs.

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 described, and the checksum-vs-register caveat is present. However, for a 2-parameter validator with no annotations, the missing account-format guidance and unexplained jurisdiction parameter leave the definition meaningfully short.

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 0% for 2 parameters, so the description must compensate. It never mentions the expected account format (e.g. bank-branch-account-suffix) or explains the unexplained 'jurisdiction' parameter with its default of NZ on an explicitly NZ-only tool — leaving both inputs ambiguous.

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 an NZ bank account number') and names the exact algorithm applied, which is far beyond a tautology. It is distinguishable from validate_ird and validate_abn by resource, though it never explicitly says 'this is not the IRD number tool' — a real risk given the oddly overlapping 'Inland Revenue algorithm' phrasing.

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 'Free:' prefix implies a paid tier exists and thus a usage context, and the checksum-only statement hints at when the tool is sufficient. But there is no explicit when-to-use routing against siblings like validate_ird, nor any statement of when a paid/full-register check is required instead.

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