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

With no annotations, the description carries the full behavioral burden. It usefully discloses the core integrity rule ('a hash mismatch is refused'), which is real behavioral context, but leaves open who may approve, whether approval is idempotent, whether it locks or freezes the brief, and what happens on retry.

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 key constraint (hash mismatch refused) is placed at the end as a caution, and the object of the operation is front-loaded.

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 mutation tool with no annotations, no output schema, and 5 undocumented parameters, the description covers only the central semantics. It says nothing about return values, error behavior beyond the refusal, or the three unexplained scalar parameters, so an agent would still be guessing about invocation details.

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

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

Schema coverage is 0% for 5 parameters. The description explains the roles of brief_hash (must equal the current hash) and variant_hashes (per-platform hashes being approved together), but gives no meaning for brief_id, approver, or approved_at, and does not hint at the nested shape of variant_hashes.

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: recording the owner's approval of the current brief hash plus variant hashes. It is clearly distinguishable from siblings like brief_read, brief_create, and brief_update, though it does not name any of them for contrast.

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 explicit when/when-not guidance. The phrase 'EXACT current brief hash' hints that the brief must be read first, but the description never says to call brief_read beforehand, nor when to prefer this over brief_update.

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 does add real behavioral context: EXIF-strip status is recorded per photo, license_required accepts unknown|no|yes:<type>, and the tool issues a version-1 hash that approval binds to. It omits mutation-safety details such as permissions, idempotency, behavior on duplicate brief_id, and what happens to uploaded photos.

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 body is one dense run-on sentence enumerating a dozen fields with no grouping or line breaks, which makes it harder to parse than its length warrants. Most content earns its place, but the structure undermines readability.

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 14-parameter mutation tool with no annotations and no output schema, the description covers the domain fields well and notes the version hash. It still leaves required-vs-optional expectations, validation rules, failure behavior, and the relationship to brief_read/brief_update unexplained.

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 14 parameters, so the description must compensate and largely does: it names or characterizes category, service, scope with statement/items, ZIP-tier location, timing window, ceiling, tip policy, photos, safety/access, intended/prohibited platforms, and details. It adds semantics the schema lacks, notably the license_required value space, but leaves brief_id unexplained and gives no format detail for the nested objects.

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 specific verb and resource — 'Create a canonical Task Brief' — and enumerates the domain content that distinguishes a brief from a generic record. It does not explicitly contrast with brief_update or brief_approve, so sibling differentiation is left to the verb 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?

Usage is implied by the lifecycle framing ('Issues the version-1 hash an approval binds to'), which suggests this precedes brief_approve. However, there is no explicit when-to-use, no statement of prerequisites, and no routing guidance to brief_update for modifications or brief_read for retrieval.

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 disclose useful output context—version, hash, and approval validity—but says nothing about permissions, failure behavior for unknown brief IDs, or whether any validation side effects occur.

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 short sentence with the action and resource front-loaded and no wasted words. It is appropriately sized for a one-parameter read tool.

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 one-parameter read with no annotations or output schema, the description covers the core operation and highlights return fields. However, it leaves gaps around ID semantics, error cases, and what "approval validity" concretely means.

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 required brief_id, so the description should compensate but does not. "Read a brief" only restates the obvious linkage; it adds no format, source, or scoping semantics for the identifier.

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 ("Read") and resource ("brief") and adds what the response contains (version, hash, approval validity). It is clearly a read operation, distinguishing it from sibling write tools like brief_create and brief_update, though it does not explicitly name those 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?

Usage is implied by "Read a brief" with a required brief_id, but the description gives no explicit guidance on when to use this versus alternatives such as brief_approve or quote_read. No exclusions or prerequisites are stated.

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 must disclose the tool's behavior, and it does disclose major points: each edit creates a new version, a post-approval edit invalidates the approval, and the brief returns to draft. It omits what happens on failure, whether concurrent edits conflict, and whether the old version remains retrievable.

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 sentences, zero filler. The primary action is front-loaded, and the spec citation supports the downstream consequence.

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?

This is a mutation tool with no annotations, no output schema, and a nested object whose schema is undocumented. The description covers versioning and approval invalidation well, but it does not explain the shape of 'changes' and does not state what a successful call returns, even a new version id.

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 the nested 'changes' object is completely undocumented. 'Content-field changes' hints at its purpose, but the description does not state whether it needs a patch or a full replacement, which fields count as content fields, or the role of brief_id in versioning. The description must fill this gap and does not.

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: 'Create a new brief version from content-field changes.' This distinguishes it from brief_create, which creates the brief itself, but it never refers to its siblings briefly, so a reader must guess the difference between updating a brief and creating a brief version.

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 phrase 'from content-field changes' only implies when to use the tool: it is for edits to content fields of an existing brief, not for metadata edits. The description names no alternative and states no exclusions, even though brief_create, brief_read, and brief_approve sit alongside it.

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 real behavior: platform state is stored verbatim and separately, and an unattested platform-completed claim creates an exception record (spec 7.2). That is meaningful side-effect disclosure, but permissions, idempotency, and whether the brief itself is mutated 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?

Two tight sentences, front-loaded with the core action before the edge-case rule. Dense but every clause carries information; the spec citation is the only slightly noisy element.

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 10-parameter tool with zero schema descriptions, no annotations, and no output schema, the description covers the conceptual model and the exception rule but leaves most input fields undefined. An agent could call it with only brief_id but has no basis for populating the other nine fields.

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 0% across 10 parameters, so the description must compensate and largely does not. It implies meaning for scope_results and platform_state, but quote_id, timeliness, verified_at, communication, quality_notes, pro_display_name, and platform get no explanation anywhere in the definition.

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 object: verify completion against the brief's scope statement, with the output shape (each scope item done/partial/not_done with owner attestation). That is clearly distinguishable from siblings like brief_read or review_draft, though it never explicitly names an alternative or states whether it is a pure read or a mutation.

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 explains an internal rule (an unattested platform-completed claim opens an exception record) but gives no guidance on when to call this versus review_draft or receipt_list, no prerequisites, and no statement of what state the brief must be in first. Usage must be inferred entirely.

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 load well: it states it executes nothing, that it is 'receipted either way,' and gives the exact return vocabulary (ALLOW / MANDATE_ALLOW_PERSON_PENDING / DENY with named reasons). It does not cover auth requirements or what the receipt/receipt_list interaction involves, so it stops short of full 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?

One dense paragraph, front-loaded with the purpose and the check list, with the crucial 'executes nothing' caveat early. The comma-separated checklist is terse but every clause carries information; no filler sentences.

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 6-parameter, nested-object tool with no output schema, the description does supply return values and the no-side-effects caveat. But it leaves the `mandate` object, `as_of`, and the meaning of 'receipted' unexplained, so an agent still has gaps before calling it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning to the token parameters (person_confirm_token tied to v1 owner-confirm, quote_approval_token tied to the approval threshold 'for THIS quote'), but it never names parameters and leaves `as_of` and the nested `mandate` object undefined.

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 specific verb and resource: 'Evaluate a hire against a live Procure/Agent Wallet mandate,' and enumerates the exact checks performed. It is clearly distinct from the brief_*, quote_* and completion_verify siblings, though it does not name which to use instead.

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 (run this check before selecting or hiring), and it notes 'v1 person-selection always needs an owner-confirm token,' which is a real condition. However, there is no explicit when-to-use/when-not or routing to an alternative tool, so the agent must infer the trigger.

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 supplied, so the description carries the full burden; it does add real behavioral detail — unexposed fees force an UNEXPOSED status with no all-in, and totals are kept separate from face price. However, it never says whether normalization is a pure computation or persists a record, nor anything about validation failures beyond the unexposed case.

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 that front-load the core transformation and follow with the output shape and the one optional behavior. The phrase 'kept separate forever' is stylistic but encodes a real modeling constraint, so little 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 15-parameter tool with nested objects, zero annotation coverage, no output schema, and 0% schema descriptions, the definition does not do enough: the return shape (the normalized record) is described only loosely, and most input parameters remain unexplained. An agent would have to guess at hour_cap, owner_fee_exception, and fees_exposed.

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 15 parameters, and the description documents only a handful: the model values (lead_model, stated_budget, fixed_price, hourly), fee bearers, tax, and ceiling_all_in. Eleven parameters — pro, tip, currency, hour_cap, job_price, hourly_rate, valid_until, fees_exposed, raw_quote_ref, owner_fee_exception, platform — carry no meaning in either the schema or 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?

States a specific verb and resource (normalize a quote) and enumerates the four supported quote models, which lets an agent distinguish it from the sibling quote_read. It never explicitly contrasts itself with quote_read, but the 'into one record' framing makes the transformation clear.

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 explains what it produces but not when to reach for it instead of quote_read or hire_check, nor any prerequisite for normalizing a quote. The only usage hint is 'Optional ceiling_all_in runs the ceiling test,' which is a parameter note rather than 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?

With no annotations, the description carries the full behavioral burden. It mentions an optional ceiling re-run but does not disclose permissions, whether that re-run has side effects, expected return shape, or failure 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 description is a single tight sentence with the main action front-loaded and no filler. It uses minimal space to convey the core read operation and optional parameter effect.

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 are no annotations and no output schema, and both parameters lack schema descriptions. For an agent to call this correctly, the description should explain more about quote_id, what a normalized quote contains, and what the ceiling test affects.

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 gives some meaning for ceiling_all_in ('re-runs the ceiling test') but does not explain quote_id's format or source, leaving required parameter semantics under-specified.

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: read a normalized quote. It is clear enough to distinguish basic reading from sibling tools like quote_normalize, though it does not explicitly name an alternative.

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 by 'Read a normalized quote' and the optional ceiling_all_in parameter, but the description does not say when to use this versus quote_normalize or other siblings, nor when not to use it.

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 meaningful traits: the log is append-only and hash-chained, which tells the agent entries are immutable and integrity-verifiable. It does not say whether verification always runs, how a broken chain is surfaced, ordering, or cost, which matters for an audit 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?

A single front-loaded sentence with no filler, and the key property (append-only hash chain) appears before the secondary 'verify' clause. Brevity is appropriate, though it may be over-compressed given the unanswered behavioral questions.

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?

No output schema, no annotations, and an undocumented 'limit' parameter leave the agent unable to predict return shape or verification semantics. For a read tool that claims to also verify a hash chain, the description should say what verification produces and how failures appear.

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?

There is one parameter ('limit') with 0% schema description coverage, and the description never mentions it, neither its default, maximum, nor whether it caps receipts or verification work. With low coverage the description should compensate, and it does not.

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 ('List ... gig-core receipts') plus an extra capability ('verify the chain'). No sibling tool touches receipts, so the resource itself distinguishes it, but the coupling of two operations (list vs verify) in one sentence leaves mild ambiguity about what the call actually does.

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 'append-only, hash-chained' auditing framing; there is no explicit when-to-use, when-not-to-use, or alternative named among siblings such as brief_read or completion_verify. An agent can infer it is the audit-trail reader, but nothing in the text confirms that.

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 burden and does real work: it discloses a refusal behavior (leverage language rejected at draft time), a grounding constraint (no sentiment not in the record), and a non-mutating guarantee ("never submits itself"). Gaps remain around error behavior for an invalid verification_id and any permission requirements.

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 tight sentences, each earning its place, with the core grounding constraint front-loaded. Slight awkwardness in the compound "timeliness/communication/quality" clause but 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, so the description should characterize the returned draft (length, structure, whether it is plain text). It also stops short of the obvious next step, submitting or approving the draft, which matters for a single-parameter drafting tool in a brief workflow.

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 the single parameter, verification_id, is entirely undocumented. The description only implies it references an existing verification record; it says nothing about format, where to obtain the ID, or whether the record must be in a particular state.

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 ("Draft review text") and pins the input source to a verification record only. The scope constraint ("what was hired, what was verified, and timeliness/communication/quality strictly as recorded") makes it clearly distinct from the brief_* and completion_verify siblings, 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?

Usage is implied through hard content constraints (record-only, no added sentiment, leverage language refused) rather than stated as when-to-use/when-not. It never tells the agent what alternative to use for a freeform review or how the draft eventually gets submitted, leaving the workflow after drafting to inference.

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