HourProof — volunteer/service hour ledger (no AI)

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

No annotations are provided, so the description carries the full burden. It does disclose one real behavioral fact beyond the schema — the bearer-key auth requirement — but says nothing about whether appends are idempotent, how failures surface, or whether existing entries are affected. Partial disclosure only.

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

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

Two short sentences, front-loaded with the action and followed by the one hard prerequisite. Nothing wasted.

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

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

With no annotations, no output schema, and 0% parameter documentation, the description is the only guidance an agent has — yet it omits the entry object structure, mutation/reversibility behavior, and error conditions. Inadequate for a write tool with a nested payload.

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% and entries is an array of unconstrained objects, so the critical shape of each entry (fields, units, required keys) is documented nowhere. The description contributes only that entries represent "logged hours"; record_id gets no added meaning.

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 (append) and resource (logged hours) scoped to an existing record, which implicitly separates it from the sibling create_record. Clear enough for an agent to select, though it never names an alternative 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?

"to an existing record" implies the precondition that a record must already exist, and by contrast hints that create_record is the path for new records. No explicit when/when-not or named alternatives, so the guidance stays implicit.

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 full burden and does well: it declares the operation is deterministic arithmetic with no AI, enumerates exactly what it validates, and explicitly disclaims the judgment it does not perform. It omits return shape and any auth/permission notes, keeping it from a 5.

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

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

Two tightly packed sentences, front-loaded with the tool's purpose and scoping, with the exclusion placed at the end as a boundary. 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?

For a validator with no output schema, the enumerated check categories effectively convey what problems will be reported. It stops just short of describing the response format or error-reporting structure, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, including as_of's future-date semantics and the entries shape. The description adds only the 8-hour flag concept, which is marginal over the schema, so baseline 3 applies.

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

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

States a specific verb (check) and resource (logged service/volunteer hours) plus the exact scope of the check: bad dates, non-positive/impossible totals, missing organization, and over-flag days. It is clearly distinguishable from write-oriented siblings like add_entries and create_record.

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 negative boundary ('does NOT decide whether the hours satisfy any school or award requirement') implicitly routes the agent elsewhere, likely get_rules, and clarifies this is an internal-consistency validator only. No sibling is named explicitly, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden, but it does disclose two genuinely useful behavioral facts absent from structured data: a bearer key is required and the call returns a record id. It still omits write-side traits an agent needs, such as whether it is idempotent, what happens on duplicate student_name, or whether it replaces an existing ledger.

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 the action first, the return value parenthesized, and the auth requirement last. 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?

A 4-parameter mutation tool with no annotations, no output schema, and 25% schema coverage gets a one-line description. The agent cannot tell what the period parameters do or what the created ledger contains, which is too thin for this complexity.

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

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

Schema description coverage is only 25%, so the description must compensate and largely does not. It alludes to student_name ('one student') but says nothing about what period_start/period_end bound or how program is used, and period_end/period_start have no schema descriptions either.

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

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

States a concrete verb+resource: 'Open an hour ledger for one student', plus the return value (a record id). This distinguishes it from read-only siblings like check_hours or get_record_summary, though it never names an alternative 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?

No when-to-use guidance and no comparison to siblings such as add_entries (which presumably populates the ledger this opens). The implied usage is only that a ledger gets created, leaving the agent to infer ordering and prerequisites.

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, and it does disclose one real trait — the bearer-key auth requirement, which the schema does not encode. However it never confirms read-only/non-mutating behavior, idempotency, pagination, or how large 'every issue found' can get, leaving meaningful gaps for an unannotated 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?

Two short sentences, front-loaded with the returned content before the auth caveat. Nothing is padded, though the terse phrasing borders on under-specification rather than tightness.

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 usefully enumerates what comes back and notes the auth requirement, which is enough to attempt a call. It still omits when the tool is appropriate and any detail on the undocumented record_id, so completeness is only minimum-viable.

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 parameter, so the description must compensate. 'For one record' only loosely signals that record_id identifies a single record; it adds no format, source, or expected-value guidance (e.g. ID shape, where to obtain 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 names the concrete payload of the tool — totals, a per-category breakdown, and every issue — scoped to 'one record.' That is far more specific than a restated name, though it never states the verb and never differentiates itself from siblings like get_rules or check_hours.

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 at all: no statement of which situations call for a record summary versus add_entries, check_hours, or get_rules. 'Requires a bearer key' is a prerequisite, not usage routing, so an agent gets no help choosing between this and its 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?

No annotations exist, so the description carries the full burden. It goes beyond a bare content label by disclosing that the table includes the reason each rule is checkable and, notably, what it explicitly does not claim — a genuine scope/limitation disclosure. It stops short of describing read-only semantics or format, but for a zero-parameter lookup that gap is small.

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 compact sentences, the content characterization front-loaded and the usage hint trailing it. There is no filler or restatement 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?

With no output schema, the description must sketch the return value, and it does: a rule table, per-rule rationale, and stated non-claims. That is enough for an agent to decide whether to call it and how to use the result, though the shape of the payload remains somewhat abstract.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description correctly adds no parameter guidance, which is appropriate.

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

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

The description names the resource precisely — 'the exact rule table this service checks against' — so an agent knows it returns the authoritative validation rules rather than records or signoffs. It doesn't explicitly contrast with siblings like get_record_summary or check_hours, but the resource is distinctive enough to stand apart.

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 clause 'Quote it if you need to explain a result' gives one concrete usage scenario, which is more than nothing. However, it never states when to reach for this versus get_record_summary or check_hours, so the agent must infer that this is a reference/lookup 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?

With no annotations, the description carries the full burden, and it does disclose two useful traits: a bearer key is required, and the token is single use. It omits other relevant behavior such as token expiry, whether previously issued links are invalidated, and whether creating the link mutates the underlying record.

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, front-loaded sentences with the core purpose first, then auth, then the single-use constraint. Minor redundancy: 'one-time URL' and 'The token is single use' restate the same property.

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 three-parameter mutation with no output schema and no annotations, the description covers purpose and the key constraint but leaves the parameters entirely unexplained and never states how the generated URL is returned. Adequate but with clear 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% across three parameters, so the description must compensate but adds nothing about record_id, supervisor_name, or supervisor_email. At best, 'the recorded hours' loosely hints that record_id identifies a work record.

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+resource: 'Create a one-time URL' for supervisor confirmation of recorded hours, which is clearly distinct from siblings like create_record or check_hours. It never names or contrasts a sibling tool, so differentiation is only implicit.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no alternatives named (e.g., when to request signoff vs. just reading hours with check_hours). The usage is only inferable from the stated purpose.

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