emendrix

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

With readOnlyHint/idempotentHint already covering the safety profile, the description adds a great deal: `omitted` counts rows past `limit`, empty lists mean no matching date in the window, every list is complete only for the covered watch window, `disputed` is one of three independent signals with `dispute_reason` naming which, `applies_from: unknown` does not mean no date applies, and single-signal units surface as metadata_only_units/instruction_only_units. It also disclaims that output is machine-computed and not legal advice.

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 is front-loaded in the first clause, and nearly every sentence carries non-obvious semantics rather than filler. However, it is delivered as one dense, semi-colon-chained block with no structure separating field semantics, dispute handling, and disclaimers, which hurts scannability.

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 temporal change-detection query over legal texts, the description supplies the interpretive context an agent needs (window completeness, dispute semantics, unknown-date semantics, unit-name handling), and an output schema exists so return structure needn't be restated. The one gap is routing guidance among the many sibling query tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it spells out what each `basis` enum value represents (`updated_on` = event or latest repair, `detected_on` = when the run saw it, `in_force` = in-force date, with rows lacking one dropped), and clarifies that `omitted` corresponds to rows past `limit`. It does not add anything for `acts`, `since`, or `include_disputed`.

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 gives a precise verb+resource+scope: list recorded changes where the `basis` date is on or after `since`, newest first. It is unambiguous about what the tool returns, but it never names or contrasts a sibling (e.g. list_disputed, get_change, provision_history), so it stops short of the 5 bar.

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 usage context (querying changes within a date window) and layers on interpretation rules, but it never states when to prefer this tool over find_substance, provision_history, or list_disputed, nor any exclusions. Usage is inferred rather than directed.

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 only cover safety (readOnly, idempotent, closed-world), but the description adds substantial behavioral context: it never reads law text, an empty list is a meaningful negative, lists are complete only for the covered watch window, and the meaning of `disputed`, `dispute_reason`, `applies_from: unknown`, and `metadata_only_units`/`instruction_only_units` are all explained. This is exactly the value-add beyond structured fields.

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 is front-loaded in the first sentence, which is good. But the remaining text is a dense run-on of clauses and a legal disclaimer that could be tightened; several semantic points are valuable but are packed without structural separation, making it harder to scan.

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

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

An output schema exists, so the description is not obligated to document return shape, yet it still explains the key non-obvious return semantics (dispute signals, unknown application dates, single-signal units, window completeness). For a tool of this complexity it is nearly complete, with the main gap being the absence of sibling-routing guidance.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description's framing ('whose canonical location string or stored heading contains `query`') largely restates the schema's own wording for `query` and adds no new format or syntax detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource: 'Find touched provisions of one act whose canonical location string or stored heading contains `query`, each with its newest row.' It scopes to one act and a match rule, which is clear. However it does not explicitly differentiate from closely named siblings such as provision_history or find_substance, leaving the agent to infer the boundary.

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

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

Usage is implied through output semantics (empty list meaning, watch-window completeness) rather than stated as when-to-use guidance. It never names an alternative tool or a condition that selects a sibling over this one, so the agent must infer routing from context.

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

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

Annotations already establish a safe read-only, idempotent, closed-world operation, but the description adds substantial behavioral context: it reports where numbers appear, decides nothing about legal status, explains disputed and dispute_reason signals, clarifies applies_from: unknown, and explains metadata_only_units and instruction_only_units. These are meaningful output semantics beyond what annotations 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?

The purpose is front-loaded, but the description is very dense and runs through many caveats in long, clause-heavy sentences. It also repeats the non-legal-advice idea twice, and could be more scannable without losing necessary 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 complex, output-heavy tool with an existing output schema, the description supplies important decision caveats and watch-window scope so an agent can interpret results correctly. It is nearly complete, though sibling-tool routing and any pagination or response-shape limits are not addressed.

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 input schema already documents the sole identifier parameter as a CAS, EC, or CLP Index number with hyphens optional. The description repeats the hyphens allowance and mentions CAS/EC but adds no syntax, format, or validation detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Find the entries that print a CAS or EC number' in the newest versions and recorded changes. It is clear what the tool retrieves, but it does not explicitly distinguish itself from siblings such as find_provisions or list_disputed.

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 no when-to-use guidance, no when-not-to-use guidance, and never names an alternative sibling tool. The hyphens note is parameter-level guidance, not usage routing.

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

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

Annotations already cover the read-only/idempotent/closed-world profile, and the description layers substantial extra context on top: pagination via the '[… N characters omitted, continue with offset=M]' marker, the exact completeness scope of every list ('from the oldest version an act was watched from to its newest'), the meaning of `disputed`/`dispute_reason`, the specific reading of `applies_from: unknown`, and the legal-advice disclaimer. These are non-obvious interpretation rules an agent would otherwise misread.

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

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

It is front-loaded with the core purpose, and several sentences (the `disputed` definition, the `applies_from: unknown` clarification) genuinely earn their place. But it is a single dense paragraph mixing field semantics, completeness scope, and a legal disclaimer, which is hard to scan for an agent that only needs the invocation essentials.

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, yet the description still explains the subtle field semantics that the schema cannot. For a high-complexity legal-diff tool this is largely complete, with the main remaining gap being behavior on missing identifiers or empty results.

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 goes beyond the schema by spelling out the truncation marker produced by `max_chars` (1 to 50000), the paging semantics of `offset`, and the 'counts repeats of one location in one event from 1' definition of `occurrence`. That is real added meaning, though `act`, `version`, and `location` are left entirely to 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 opening 'One change in full' names a specific verb and resource and enumerates exactly what the record contains (before/after text, cited sentences, signals, gate outcome), so an agent knows what it retrieves. However it never contrasts itself with siblings like get_event, provision_history, or changes_since, so the singular-vs-list distinction must be inferred from the name alone.

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

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

The description is rich on output semantics but gives no explicit when-to-use, when-not, or alternative routing. It only references `list_acts` incidentally to explain the `act` key format, not as a selection rule, leaving the agent to infer that this is the detail fetch after a list call.

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 cover safety (readOnly, idempotent, closed-world), and the description goes well beyond them: it defines what `disputed` and `dispute_reason` mean, guarantees the lists are complete for the record's watch window and say nothing outside it, and explicitly states that `applies_from: unknown` means non-deterministic parsing rather than no date. metadata_only_units/instruction_only_units semantics and a machine-computed legal disclaimer round out the disclosure.

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

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

It is front-loaded with what the record contains, but the single dense paragraph mixes output-field definitions, completeness guarantees, and a legal disclaimer, with heavy inline backtick terminology. Each clause carries some information, yet the block is longer and harder to scan than the two-parameter lookup requires.

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

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

An output schema exists, so return-value structure need not be re-explained, yet the description usefully clarifies field semantics (disputed, dispute_reason, applies_from, *_only_units) and scoping. It omits any prerequisite that act/version come from list_acts, which is the remaining gap.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (act key/corpus-key, version or entry key). The description adds no format or lookup guidance beyond that, so the baseline 3 applies.

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

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

The description states what the tool returns with substance: one event of one act, with its counts, repairs, corroboration signals, and every row. That is far more specific than a restatement of the name. It stops short of naming a sibling (e.g. get_change) to disambiguate 'event' vs 'change', which is the only thing keeping it from a 5.

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

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

Usage is only implied: the required act+version pair signals a single-record lookup, and the sibling list includes get_change/changes_since that are never mentioned. There is no explicit when-to-use or when-not-to-use statement, so the agent must infer routing from the description's substance.

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 openWorldHint=false, yet the description adds substantial behavior the annotations cannot: watch-window completeness guarantees, the meaning of an empty list, the three independent dispute signals behind `disputed`/`dispute_reason`, the `applies_from: unknown` semantics, the metadata_only_units/instruction_only_units naming, and an explicit legal-advice disclaimer.

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 correctly front-loaded in the first clause, and most sentences carry distinct semantics about edge cases. However, the closing disclaimer is stated three times over ('no lawyer's review', 'engineering assistance only', 'not legal advice'), and the single dense paragraph of caveats could be trimmed without losing information.

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

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

An output schema exists, so return values need not be explained, yet the description goes further and defines the semantics of disputed, dispute_reason, applies_from and the *_only_units fields. Combined with completeness guarantees across the watch window, the agent has nearly everything needed; only the boundary against sibling list tools is unstated.

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 adds real meaning beyond the schema's terse 'Part of a key, title or alias' and 'A catalogue sector' by specifying that `query` matches case-insensitively and that `domain` matches the catalogue's sector specifically.

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 ('List the acts the record holds') and enumerates what each entry carries (label, aliases, sector, newest version, updated_on, counts). It is far from a tautology. It does not, however, explicitly distinguish this tool from close siblings such as list_disputed or changes_since, so the agent must infer the boundary.

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

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

There is no statement of when to pick this tool over the alternatives in the sibling set. The description explains what `query` and `domain` do and what an empty list means, but never names a competing tool or a selecting condition. Usage has to be inferred from the scope phrase 'the record holds'.

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 openWorldHint=false, so the safety profile is covered. The description adds valuable context beyond that: window semantics, what 'disputed' means (three independent signals), 'applies_from: unknown', and that metadata_only/instruction_only units are named but not listed as changes. However it omits return format and pagination/ordering behavior, so it's solid but not exceptional.

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 is front-loaded in the first sentence, but the definition sprawls across many dense sentences covering caveats, signal semantics, edge cases, and a legal disclaimer. Much of this is verbose and could be tightened, weighing against conciseness.

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

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

With an output schema present, the description needn't explain return values, and it goes further by clarifying window scope, the meaning of `disputed` and `dispute_reason`, unknown-date semantics, and the non-legal-advice framing. An agent has enough to interpret and call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (act, limit, reason). The description adds only marginal detail, notably that `omitted` counts rows past `limit`, which is baseline-appropriate when the schema carries the load.

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 opening sentence states a specific verb and resource: 'Disputed rows grouped by their stored `dispute_reason`.' It's clear this is a filtered listing of disputed changes, but it never distinguishes itself from siblings like get_event or changes_since, so an agent must infer the boundary.

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

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

It explains result semantics ('an empty list means no recorded change in the window is disputed for that filter') and the watch-window scope, which implies usage. However, it never states when to prefer this over find_provisions, find_substance, or get_change, and offers no explicit alternatives.

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

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

Annotations already establish the safety profile (readOnlyHint, openWorldHint=false, idempotentHint=true), so the description is free to add interpretation rules — empty result meaning, window completeness, the three-signal meaning of `disputed`, `applies_from: unknown`, units listed by name only, and an explicit 'not legal advice' caveat. This is substantial behavioral context beyond the annotations, though some of it describes output semantics rather than tool 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?

The definition is front-loaded with the core purpose, but it is long and repetitive — the window is asserted in sentence one and re-asserted in sentence three, and the dense dispute/applies_from passages read as output documentation that the output schema could carry. Substantively useful, but not tight.

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 whose output encodes disputes, watch windows, unknown application dates, and single-signal units, the description covers every interpretive trap an agent would hit, and the output schema handles the structural shape. An agent can consume the result correctly without external documentation.

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%: both `act` (with its `corpus/key` form pointing at list_acts) and `location` (canonical string like `AR 50`) are fully documented in the schema. The description adds nothing about either parameter, so the baseline 3 applies.

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

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

The first sentence gives a specific verb and resource: it returns every recorded change to one top-level provision, ordered newest first, with the covering window. The scope ('one top-level provision') separates it implicitly from a cross-provision tool like changes_since, but no sibling is actually named, so the agent must infer the boundary.

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

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

There is no when-to-use/when-not statement and no alternative is named (e.g., get_change for a single change, changes_since for a time-window query). The text explains how to read the result, not when to choose this tool over its siblings, leaving selection entirely to inference.

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