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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation and repeat-call profile is covered. The description adds nothing beyond a rephrasing of the purpose: it does not say what state changes (assigned -> accepted), whether prior acceptance errors, or what the caller sees afterwards.

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 role tag and the action, with no filler. The second sentence is a mild restatement of the first rather than new information, which keeps it from a 5.

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 one-parameter state transition with annotations covering the safety profile and no output schema, the description is merely adequate. It omits prerequisites, failure behavior, and whether the task must be assigned to the calling agent, all of which matter 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?

There is a single parameter with 100% schema description coverage ('Task ID to accept'), so the schema carries the semantics. The description never mentions task_id, which is acceptable at this coverage level but adds no value.

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 ('Accept') and resource ('your task assignment'), which is enough to separate it from siblings like assign_agent, complete_task, and submit_evidence. The added clause 'Confirms you're ready to work' clarifies what acceptance means, though it does not explicitly name the siblings it is not.

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 '[ANY ROLE]' tag signals who may call it, which is useful, but there is no when-to-use guidance, no prerequisite (an assignment must exist first), and no statement of when to prefer this over complete_task or submit_deliverable. Usage is implied at best.

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=false, idempotentHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is mostly covered structurally. The description adds only the word 'pre-authorized' as a precondition hint, and says nothing about consequences of activation, whether it can be reversed, or what authority is required.

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, front-loaded with the action and resource, with no filler. It is efficient, though its brevity reflects under-specification rather than disciplined 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?

For a non-idempotent mutation tool with no output schema and only 25% parameter coverage, the description is too thin: no precondition detail, no post-activation behavior, and no explanation of the required validity window. An agent could invoke it but could not confidently predict or verify the outcome.

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 carries the burden — and it only alludes to trigger_evidence ('with evidence') while saying nothing about pathway_id, valid_until, or the trust_epoch default. The one parameter whose semantics matter most (the validity window) is entirely unexplained.

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 ('Activate a pre-authorized emergency pathway'), which is far clearer than a tautology. It implies a distinction from the sibling define_emergency_pathway (activation vs. definition) but never names it explicitly, so sibling differentiation is left to inference.

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 tool versus define_emergency_pathway, no statement of prerequisites (e.g., that the pathway must already exist), and no exclusion or fallback condition. The agent must infer all routing from the tool name alone.

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=false, idempotentHint=false, and destructiveHint=false, so the mutation profile is covered structurally. The description adds nothing beyond restating the name: it does not disclose that required signer private/public keys are needed, what happens on duplicate signatures (non-idempotent), or any authorization requirement. For a signing operation handling secrets, this is thin.

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 clean, front-loaded sentence with no filler, so it is not bloated. But it is terse to the point of under-specification for a mutation involving cryptographic keys, so brevity buys little.

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 exists, so return values need not be described, but the description still omits prerequisites (an existing approval request), the purpose of the signer key pair, and error/duplicate behavior. With 5 undocumented parameters and no usage guidance, the definition is not complete enough 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 five parameters, including the required signer_private_key, signer_public_key, and request_id plus an office_id and a key_class with default 'board'. The description mentions none of these and provides no compensating detail, leaving the agent to guess at key format, key_class semantics, and when office_id 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 a specific verb and resource: adding a signature to an approval request, which is clearly distinguishable from create_approval_request. However, it offers no explicit differentiation from other signing siblings such as sign_charter, sign_amendment, or aps_sign_attribution_consent, so the agent must infer scope from the noun 'approval request' 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?

There is no when-to-use guidance, no statement that an approval request must already exist, and no mention of alternatives. The agent gets no help deciding between this tool and create_approval_request or the other sign_* tools.

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

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

Annotations already disclose that this is a non-readOnly, non-idempotent write with no destructive or open-world effect, so the safety profile is covered. The description adds nothing beyond that — it does not say whether a principal report can be overwritten, appended, or duplicated, despite idempotentHint=false making that ambiguity consequential.

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 with no filler and the core action front-loaded. It is efficient, though the brevity comes at the cost of the missing detail scored elsewhere.

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 four-required-parameter mutation with no output schema, zero schema descriptions, and no usage context needs far more from the description than this. The agent is left guessing about parameter formats, enum semantics, and when the tool should be called.

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 all four parameters are undocumented in the schema. The description names none of them (outcome_id, observed_outcome, outcome_class, divergence_score), so the agent gets no meaning for the enum values, the 0-1 divergence_score scale, or how the principal's view relates to the existing outcome 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?

States a specific verb and resource ('Add principal's perspective to an outcome record') and ties it to a named concept, three-way divergence reporting. It is distinguishable from siblings like create_outcome_record, though the 'three-way divergence' framing is never explained, so the agent only half-understands what differentiates this side-record from the base outcome.

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 prerequisites, and no reference to the obvious alternative create_outcome_record. The agent cannot tell from this text whether a principal report is mandatory after every outcome or an optional addendum.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing about what the downgrade computes, how the ratio/default tier are used, or what the result represents. The word 'apply' sits in tension with readOnlyHint, though 'foreign' reputation plausibly implies a computed evaluation rather than a persisted write, so this is not scored as a contradiction.

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

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

A single front-loaded sentence with no wasted words, which is good structural hygiene. However, at this level of domain complexity and schema under-documentation, the brevity crosses from concise into under-specified.

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 seven-parameter tool with 14% schema coverage, five required inputs, no output schema, and opaque domain jargon, one sentence is completely inadequate. An agent has no basis to choose correct values for any required parameter or to predict the result.

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 14% (one of seven parameters documented). The description provides no meaning for agent_id, origin_gateway_id, attested_tier, attested_diversity_score, downgrade_ratio, or foreign_default_tier, so it fails to compensate for the schema gap that the low coverage requires.

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 (apply) and a specific resource (import policy downgrade to a foreign vouched reputation), not a tautology of the title. The domain vocabulary ('import policy downgrade', 'foreign vouched reputation') is specialized but identifies the operation. It does not, however, differentiate itself from nearby reputation siblings like update_reputation or vouch_reputation.

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 indication of when this tool should be used versus alternatives, what preconditions must hold, or what triggers a downgrade scenario. The agent must infer everything from sibling names alone.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds genuine behavioral context beyond them: per-axis (D, P, G, C) contributor totals, balanced-Merkle commitments, and residual buckets pooling sub-threshold contributors. It does not disclose whether anything is persisted server-side or the key-handling/auth implications of passing gateway_private_key.

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

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

Three sentences, front-loaded with the core verb+resource and scope, then mechanics, then output nature. No filler. Slightly dense with undefined domain jargon (D/P/G/C, 'balanced-Merkle'), but every sentence contributes.

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 cryptographic aggregation tool with nested objects, no output schema, and four required parameters, the description adequately characterizes the produced artifact (fully signed, third-party verifiable) and the internal structure of the result. It omits error/edge behavior (empty receipt sets, sub-threshold threshold definition) and whether the signing key implies any side effect.

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

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

Schema description coverage is 80%, so the schema already documents period bounds, receipts, gateway_did, and the private key. The description clarifies the period's half-open semantics but adds no syntax or format detail for receipts, and the axis names (D, P, G, C) are not tied back to any parameter. Baseline 3 is 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?

States a specific verb and resource ('Aggregate a batch of Attribution Primitives ... into a signed SettlementRecord') plus the operating scope (half-open period [t0, t1)). This clearly differentiates it from siblings like aps_verify_settlement, aps_project_attribution, and generate_settlement without needing to open 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: the aggregation-over-a-period framing implies it runs after primitives exist and before verification, but the description never states when to use this tool versus aps_verify_settlement or generate_settlement, nor any prerequisite/exclusion conditions. No explicit routing guidance.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description adds genuinely useful behavior: the id is canonical and deterministic, signatures are excluded from the computation, so the result depends only on the unsigned core. That is real disclosure beyond the annotations.

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

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

Two sentences, nothing wasted, and the core action is stated first with the motivating use case second. Well front-loaded for a helper of this scope.

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 one-parameter deterministic helper with no output schema, the description conveys what is computed and why it exists. The only omission is the shape of the return value (e.g., a hex digest string), which the agent must infer.

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% for the single 'receipt' parameter, so the schema carries the parameter documentation. The description adds only the nuance that the unsigned core is what is hashed; no format or structural detail. 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 and resource: compute the canonical sha256 id of an AttributionReceipt's unsigned core. That is far more precise than the title alone and distinguishes it from creation/signing siblings. It does not explicitly contrast with the nearest sibling, aps_compute_attribution_action_ref, which is why it stops short of 5.

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

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

The phrase 'Verifiers use this to detect id tampering' gives an implied usage context (verification flow), but there is no explicit when-to-use/when-not guidance and no named alternative such as aps_compute_attribution_action_ref or aps_verify_attribution_primitive.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond that: it enumerates the returned fields, states the null case when no share exists, and explains the trust guarantee (verifiable end-to-end without trusting the gateway beyond its public key).

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 dense sentences that front-load the action and inputs before the output/verification detail. No filler, though the parenthetical field list is slightly packed.

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 exists, so the description appropriately carries the return-value burden by listing the per-axis fields and the null case. Combined with annotations covering safety, an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents record, gateway_jwks, and contributor_did. The description restates the record and DID inputs but adds no syntax, format, or constraint detail beyond what the schema provides, 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?

States a specific verb and resource ("Build a contributor-query response") plus the two required inputs and the per-axis output fields. An agent can grasp the operation without opening the schema, though it doesn't explicitly distinguish itself from nearby siblings like query_contributions, aps_aggregate_settlement, or aps_verify_settlement.

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 precondition ("given a signed SettlementRecord and a contributor DID") and the null-return edge case imply usage, but no explicit when-to-use, when-not, or named alternative tools are given. The agent must infer that this is the proof-generating step versus the aggregate/verify 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine workflow context — it is an M2-stage request consumed by the gateway — but discloses nothing about failure modes, key-material handling, or what the tool returns. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Three compact sentences, with the role of the artifact and its consumer front-loaded. The trailing 'Search keywords' line is filler but conventional and does not bloat 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?

For a 7-parameter tool with nested objects and no output schema, the description omits what is returned (a signed request object) and what prerequisites must exist first (an M1 challenge). It conveys the stage in the flow but not enough for an agent to call it correctly without inspecting the schema.

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 71%, so the schema documents most fields. The description maps three conceptual elements onto parameters (sink's M1 = challenge, delegation chain, revealed preimage = authority_token.token_preimage), which adds modest value, but freshness_beacon, subject keys, and delegation_chain_root are left to the schema. Baseline 3 given moderate coverage.

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

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

The description states a fairly specific action — the subject signs a request carrying the sink's M1, the delegation chain, and a revealed token preimage — but the tool name ('evaluate_authority') conflicts with the title/description ('Build ... Request'), leaving the agent unsure whether this tool decides permit/deny or merely constructs the input. The M1/M2 jargon is unexplained, so the resource is only partly 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?

There is no explicit when-to-use guidance and no routing against the closely related siblings (aps_capability_issue_challenge, aps_capability_mint_receipt, aps_capability_sign_effect). 'The gateway consumes this to decide permit/deny' describes downstream flow, not the condition under which an agent should call this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds the return payload (SinkChallenge + challenge_hash) and the binding role, but says nothing about the private-key handling, expiry semantics, or what happens on replay — notable for a tool that signs with a caller-supplied key.

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?

Four short sentences, front-loaded with the identity of the operation and then its return and role. The trailing 'Search keywords' line is padding but cheap, and nothing else 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?

With no output schema, the description does the right thing by naming the returned SinkChallenge and challenge_hash, and it situates the call in a larger gateway evaluation flow. However, for a 7-parameter cryptographic tool with nested objects, it omits prerequisites (sink key possession, ordering relative to sign_effect/evaluate_authority) and any expiry/freshness context.

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 71% and the description contributes zero parameter meaning: validity_seconds and required_policy_freshness have no schema descriptions and nothing in the prose explains them, while 'canonical action statement' merely echoes the action field's own description. The description does not compensate for the coverage gap.

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 concrete verb and resource: the sink 'issues a signed canonical action statement' and returns a SinkChallenge with its challenge_hash. That is more than a restatement of the name, though the sibling tools in the aps_capability_* family (evaluate_authority, mint_receipt, sign_effect) are never named or 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?

It states the downstream role ('bind the gateway's later policy evaluation to a specific action the sink authored'), which implies where this fits in a flow, but gives no explicit when-to-use, no prerequisites, and no alternatives. 'Search keywords' is retrieval metadata, not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which matches a deterministic signature over a fixed hash, so there is no contradiction. The description does add real context beyond annotations: the output is a signed permit/deny and it echoes the M2 delegation_chain_root so the sink can confirm chain agreement. However, it says nothing about the handling of the required gateway_private_key (sensitivity, whether the key is persisted, error behavior on signature failure), which an agent calling a signing tool needs to know.

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?

Roughly four sentences, front-loaded, and not bloated, but the leading 'v0.1 capability-token gateway receipt (M3)' is opaque rather than informative, and the trailing 'Search keywords' list is keyword-stuffing that consumes space without helping an agent decide or call correctly. No sentence is egregiously long, but the structure prioritizes version tags over the actual precondition and output.

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 six-parameter, five-required cryptographic tool with no output schema, the description should explain what the returned receipt looks like and when the tool is valid to call. It gestures at the receipt contents (signed decision, echoed chain root) but omits the call ordering relative to sibling capability tools, the meaning of deny_reason, and any key-handling caveats. It is not sufficient to invoke the tool reliably.

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

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

Schema description coverage is only 33%: request (partially) and policy_digest are annotated, while decision, deny_reason, gateway_public_key, and gateway_private_key carry no description in either the schema or the tool description. The description mentions challenge_hash and delegation_chain_root, which are not top-level parameters at all, so it does not compensate for the gap. With five required parameters, this leaves the caller guessing about half the inputs.

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 does name a concrete action (gateway signs a permit/deny over the sink's challenge_hash) and a concrete artifact (capability-token gateway receipt), so the mechanics are identifiable. But it is dense with undefined domain jargon ('M3', 'sink', 'delegation_chain_root') and never distinguishes itself from the closely named siblings aps_capability_issue_challenge, aps_capability_evaluate_authority, or aps_capability_sign_effect. An agent unfamiliar with the ontology can tell it produces a signed receipt but not confidently place it in the pipeline.

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. The description never says whether this is called after aps_capability_evaluate_authority, before aps_capability_sign_effect, or what precondition (an M2 delegation chain, an existing challenge) must hold first. Only a 'Search keywords' line is offered, which aids retrieval, not invocation.

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 declare destructiveHint=true and idempotentHint=false; the description earns credit by explaining WHY — the token preimage is consumed and replayed nullifiers are rejected, and M3 is verified before consumption. That causal detail is exactly what annotations alone cannot convey, though private-key handling and error behavior remain undisclosed.

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?

Roughly 70 words, front-loaded with the signing action and followed by concrete behavioral constraints. The trailing "Search keywords" list and the "v0.1 ... (M4)" version prefix are filler that slightly dilute the opening, but no sentence is redundant with the rest.

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 7-parameter signing operation with private key material, nested objects, and no output schema, the definition covers the protocol flow well but omits what the returned EffectReceipt contains and what failure modes exist beyond replay. An agent could call it, but would be guessing about the output shape.

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 57%, so the description has to do some work and it does: it maps challenge to the token preimage, challenge_receipt/gateway_public_key to M3 verification, and effect to the caller-supplied action result. It says nothing about the nested effect fields (outcome enum, executed_at, result_digest) or about expected_delegation_chain_root.

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+resource: the sink verifies M3, consumes the token preimage, and signs an EffectReceipt. The M1/M3/M4 staging implicitly distinguishes it from the sibling capability tools (issue_challenge, mint_receipt), but it never names those siblings outright, so the agent must infer which tool produces the M3 receipt it needs.

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 one explicit usage boundary is "This tool does not execute the action," which usefully prevents misuse as an executor. However, there is no statement of call ordering by tool name (e.g. call after aps_capability_mint_receipt), no prerequisitives for the keys, and no guidance on when not to call it beyond replay rejection.

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 readOnly/idempotent/non-destructive, so safety is handled. The description adds substantive behavior beyond that: replay protection, the requirement that receipts be signed and unexpired, the party-to-key binding, the explicit positive claim (citation backed by consented receipt) and negative claim (no authority to act), plus a failure mode for non-self-certifying identifiers.

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?

Front-loads the operation, then uses parallel 'What a valid result establishes' / 'What it does not establish' clauses that are easy to parse. Dense but every sentence carries semantic load; only the closing sentence on identifiers is slightly tangential.

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 defines what a passing result means and, importantly, what it does not mean, which is exactly what an agent needs to interpret the boolean outcome. Annotations cover the safety profile, so the remaining gaps are minor.

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 all three parameters are already documented in the schema. The description adds some semantic weight to the 'receipts' and 'citation' inputs by defining what a valid receipt must satisfy, but it never addresses the binding_context scoping parameter, so it stays at the baseline for high-coverage schemas.

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+resource: 'gate a binding artifact's citations', then specifies the resolution requirements each citation must satisfy. An agent can tell this is a validation/gate operation on citations, though it does not differentiate itself from the many neighboring aps_verify_* tools by name.

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

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

Usage is implied by the framing as a gate whose success criterion is spelled out, and the 'does not establish authority to act' note hints at where it sits in a pipeline. However, it never names an alternative (e.g. aps_verify_attribution_primitive, aps_check_projection_consistency) or states when a calling agent should reach for this tool rather than a sibling check.

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 readOnly/idempotent/non-destructive, so safety is covered; the description adds genuinely new value by disclosing the return shape {required, requirement?, reason?} in the absence of an output schema, and by explaining that the flag is cleared via aps_record_owner_confirmation. It does not cover auth requirements or the per_session scoping implications explicitly.

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: purpose, return shape, follow-up action — front-loaded with the escalation framing and zero 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?

With no output schema, the description must carry the return contract, and it does ({required, requirement?, reason?}). It also closes the loop with the clearing tool, so an agent has everything needed to call it and act on the result.

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 all four parameters (including session_id for per_session scope and action_details being hashed for audit) are already documented in the schema. The description adds no parameter-level syntax or format detail beyond that baseline.

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 object ('whether an action on a v2 delegation requires owner confirmation before execution'), plus frames it as an 'escalation boundary'. It is clearly distinguishable from the many other 'check_*' siblings and from aps_record_owner_confirmation, which it explicitly names.

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

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

Gives clear context for use ('before execution' of an action on a v2 delegation) and routes the agent to the follow-up tool when the flag is set. There is no explicit when-not or a named alternative check path, but the timing condition and next-step handoff are concrete.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value by spelling out the two return shapes and enumerating the four failure reasons, which is important since no output schema exists.

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

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

Two tight sentences, front-loaded with the operation and followed by the return contract. No wasted prose, though the reason enum makes the second sentence dense.

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

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

For a read-only two-input check with no output schema, the description covers the operation and return values including every failure reason. It is nearly complete; only the nature/format of an AttributionProjection is left 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%, but the schema only labels the fields ('First/Second AttributionProjection'). The description confirms both inputs are projections but adds no format, ordering, or validity constraints, so baseline 3 is appropriate.

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

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

States a specific verb ('confirm') and resource ('two projections originate from the same signed receipt'), making the cross-projection check distinct from the many sibling verify_* tools. It does not explicitly name which sibling it replaces, but the purpose is unambiguous.

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

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

Usage is implied by 'cross-projection consistency check' but there is no explicit when-to-use/when-not guidance and no comparison against adjacent tools like aps_verify_attribution_projection or aps_check_artifact_citations. An agent must infer the scenario.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine semantic context beyond them: the value is a deterministic content-addressed sha256 anchor that the four axis projections bind to, which is not inferable from 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?

Three compact sentences with the core definition front-loaded and no filler. Every sentence adds something, though the third sentence blends usage guidance into the purpose block.

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 four-parameter operation with an undocumented nested object and no output schema, the description omits how the action tuple is assembled and what role agentId, nonce, or params play. It names the output format (hex sha256) but leaves the inputs effectively unspecified.

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 four required parameters, including a nested 'params' object, and the description never enumerates or explains them. The loose phrase 'action tuple' gestures at the four fields but gives no mapping to agentId/actionType/params/nonce, so it fails to compensate for the coverage gap.

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 ('Derive') and output resource ('action_ref (hex sha256) for an action tuple'), and the follow-up sentence explains what the value is. It only loosely differentiates from the similarly-named sibling compute_action_ref, differentiating instead against 'constructing the full primitive'.

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 'Useful for indexing primitives by action without constructing the full primitive' implies a use case and a contrast with primitive construction, but there is no explicit when-not guidance and no sibling is named to route between it and compute_action_ref.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description goes beyond them by disclosing the output shape (canonical ComputeAxisEntry[] with 6-digit decimal compute_share strings summing to ~1.0) and the exact weighting formula with a default COMPLETION_MULTIPLIER of 3.0. It omits edge-case behavior (empty provider list, all-zero tokens, rounding/precision guarantees), keeping it short of 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?

Four tight sentences, front-loaded with what is computed and followed by output shape, formula, and parameter notes. Each sentence carries information, though the formula sentence is dense and could be marginally tighter.

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 carries the return-value burden and discharges it by naming the return type and the sum-to-~1.0 invariant. Combined with the downstream linkage to aps_construct_attribution_primitive, it is nearly complete; only error/edge-case behavior is unaddressed.

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 adds real meaning: it explains that `providers` entries are inference billing records whose prompt_tokens and completion_tokens drive the weighting formula, and that `profile` is an optional override. It also notes parameter names match the SDK, aiding caller construction.

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 precise verb and resource — 'Compute the C-axis fractional weight vector from a list of inference billing records' — and even specifies the input fields (prompt_tokens, completion_tokens). The 'C-axis'/'compute' framing implicitly distinguishes it from the sibling aps_compute_data_axis_weights, so an agent can route correctly without opening either 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?

The description gives clear downstream context: the output 'feed[s] directly into aps_construct_attribution_primitive,' which tells the agent where this sits in the workflow. It does not, however, state exclusions or explicitly contrast with aps_compute_data_axis_weights, so it stops short of full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial extra context: the exact return shape (DataAxisEntry[] with 6-digit decimal strings summing to ~1.0), the weighting formula, and two distinct error/edge behaviors.

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?

Front-loaded with the core action, then return shape, edge cases, formula, and parameter note in a compact block. Dense but every clause carries information, though the parameter-naming sentence is the weakest.

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 properly explains the return value (canonical DataAxisEntry[] with normalized 6-digit weights) and error behavior. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including enum values and formats. The description only restates the parameter names and notes profile is optional, adding no syntax or semantic detail beyond 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?

States a specific verb (Compute) and resource (D-axis fractional weight vector from AccessReceipt records) with clear scope. It also names the downstream sibling it feeds into (aps_construct_attribution_primitive), helping distinguish it from related aps_compute_* tools.

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

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

Gives clear context that the output feeds directly into aps_construct_attribution_primitive and describes boundary conditions (empty input -> empty array, all-zero raw weights -> error). However, it never explicitly names an alternative tool or a when-not-to-use condition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is largely covered. The description adds that the output is a complete signed object, but says nothing about the key-handling requirement implied by issuer_private_key, nor about determinism despite timestamp defaulting to now(), which sits awkwardly against idempotentHint=true.

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, zero filler: purpose first, axis legend second, return value last. Information is front-loaded and every clause carries distinct meaning.

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 nested, five-parameter cryptographic construction tool with no output schema, the description covers the return value and axis meanings but omits how the signing key is used or validated, what happens on signature failure, and whether the timestamp default affects determinism. Annotations patch part of the gap; the remaining behavioral surface is thin.

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%, which sets a baseline of 3, and the description earns above baseline by decoding the axes the schema only refers to as 'See spec §1.2': D=data sources, P=protocol modules, G=delegation chain, C=compute providers. It still adds nothing for action, issuer, timestamp, or issuer_private_key.

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 pair (build and sign) and a named resource (four-axis AttributionPrimitive for an action), and the axis legend D/P/G/C gives concrete scope. It is clearly distinct from aps_verify_attribution_primitive in direction of operation, but it never explicitly distinguishes itself from the closely-named siblings aps_create_attribution_receipt or aps_compute_attribution_action_ref.

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 instead of aps_create_attribution_receipt or the other aps_* attribution tools, and no prerequisites are given (e.g. that a valid Ed25519 issuer key must exist). 'For an action' is the only contextual hint, leaving routing entirely to inference.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds substantive context beyond them: parties must be self-certifying multibase did:aps DIDs, bare public keys or did:web identifiers will fail verification, and the output is invalid until a consent signature exists. It does not, however, explain what is returned or whether anything is persisted, leaving a mild tension with readOnlyHint for a tool named 'create'.

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

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

Three sentences, front-loaded with the core action and then constraints and follow-up. The opening label 'Representation boundary:' is opaque jargon that costs a few words without orienting the agent, but the rest is dense and free of 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?

For a nine-parameter cryptographic tool with no output schema, the description covers the semantic model, DID constraints, and the consent prerequisite well. It never states what the call returns (a receipt object, an id — a sibling aps_attribution_receipt_id exists) or what ttl_ms/gateway_id affect, which is a real gap when no output schema exists.

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 nine parameters, including the DID/key commitment requirement per party. The description restates the cross-parameter constraint (DID must commit to the key beside it) and the failure mode for bare keys, but adds little that is not already in the schema text, so the baseline of 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?

Names a specific verb and resource ('build a citer-signed AttributionReceipt') and scopes it to 'attributing a claim to a third-party principal', which separates it from siblings like aps_sign_attribution_consent and aps_check_artifact_citations. It does not explicitly distinguish itself from other receipt-constructing siblings (aps_construct_attribution_primitive, aps_create_provisional), so it stops short of a 5.

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

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

The final sentence supplies real workflow context: the receipt is 'not yet valid' until the cited principal signs via aps_sign_attribution_consent, and checkArtifactCitations gates acceptance. That is post-condition guidance rather than an explicit when-to-use-this-vs-alternative rule, and no exclusions are given, so it is implied usage at best.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding lifecycle semantics the annotations cannot express: the statement is non-binding by default until a PromotionEvent satisfies a PromotionPolicy, and dead-man expiry auto-withdraws it. It stops short of stating that the call requires the author's private key to sign, or what happens on signing failure.

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 with the framing ('Commitment boundary') front-loaded and the binding/expiry rules following. No filler, though the leading label is slightly opaque and the sentence boundaries could be sharper.

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 six-parameter, four-required signing tool with no output schema, the description covers lifecycle but not the result: it never says what the caller receives (statement id, signed artifact, receipt) or that a private key is mandatory. Annotations and the rich schema carry most of the load, so this is adequate but has a real gap around outcomes.

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% across all six parameters, so the schema already documents author, content, gateway_id, dead_man_ms, author_principal and author_private_key. The description's dead-man expiry sentence largely restates the schema's own wording for dead_man_ms and adds no format or constraint detail beyond it, 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 names a specific verb and resource ('emit a provisional statement') and scopes it to 'agent-to-agent negotiation'. It implicitly separates the provisional stage from the promotion stage (PromotionEvent/PromotionPolicy), which is the key distinction from siblings like aps_promote_statement and aps_withdraw_provisional, though it never names those siblings directly.

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 context is implied: use this for negotiation-time statements that are non-binding until promoted. There is no explicit when-not guidance, no stated prerequisites (e.g. an existing author principal/identity), and no routing to the alternative tools an agent should reach for when the statement must be made binding or retracted.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real behavioral context beyond them: the projection carries axis content plus a two-hop Merkle path and enables root reconstruction without exposing the other three axes, which is genuinely useful for an agent reasoning about 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?

Two front-loaded sentences with no filler; the purpose and output shape come first. The trailing 'axis: D | P | G | C' repeats the schema enum and is mildly redundant, costing a point.

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

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

For a read-only two-parameter tool with no output schema, the description does the important work of describing what the projection contains and what it enables downstream. It is essentially complete for invocation, with the only gap being the absence of guidance tying it into the surrounding APS attribution 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 100%, so the baseline is 3. The description restates the axis enum ('D' | 'P' | 'G' | 'C') but never decodes what D/P/G/C stand for or how the choice affects the output, and it adds nothing about the primitive parameter beyond the schema's reference to aps_construct_attribution_primitive.

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 — 'Extract a single-axis projection from an AttributionPrimitive' — and even explains the shape of the output (axis content plus a two-hop Merkle path). It is clearly distinguished from verification siblings like aps_verify_attribution_projection by being the extraction step, though it never names those siblings 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?

The clause 'lets a downstream verifier reconstruct the signed root without seeing the other three axes' implies the reason to use this tool (limited-disclosure verification), so usage is inferable. However, it never states when to choose this over aps_construct_attribution_primitive, aps_verify_attribution_projection, or aps_verify_attribution_primitive, nor any prerequisite conditions.

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

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

The description clearly describes a state-changing operation ('promote ... to binding by attaching a PromotionEvent'), yet annotations declare readOnlyHint=true. This is a direct contradiction: the tool mutates state while structured metadata claims it is read-only. Annotation Contradiction flagged.

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, front-loaded with the 'Commitment boundary' framing, with the critical caveat about dead_man_elapsed placed immediately after the core action. 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?

Covers the core mechanism and one important exclusion, which is reasonable for a 3-param tool with no output schema. But the safety profile is actively misleading (readOnlyHint=true on a mutation), and the description does nothing to correct it, leaving the agent with a wrong mental model of side effects.

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 statement, promotion_event and policy. The description adds the constraint that the PromotionEvent must satisfy the PromotionPolicy (m-of-n principal signatures), which adds semantic value beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('promote a provisional statement to binding') and names the mechanism (attaching a PromotionEvent satisfying a PromotionPolicy). An agent can distinguish this from aps_withdraw_provisional and aps_verify_promotion, though the description doesn't 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?

Provides one useful exclusion ('dead_man_elapsed cannot promote, because the dead-man path auto-withdraws the statement'), which is real routing guidance. However, it gives no explicit when-to-use context relative to aps_verify_promotion or the conditions under which a promotion should be attempted.

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?

The description says the tool builds and signs a confirmation and the tool name records one, i.e. it produces a new signed artifact, yet annotations declare readOnlyHint=true and destructiveHint=false. The only genuine behavioral disclosure (hash binding, scope modes) does not resolve this mismatch.

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 and no filler; the escalation framing is front-loaded. Slightly jargon-heavy about scope without defining the three modes, 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?

For a no-output-schema tool with annotations that are at least questionable, the description covers what is produced but omits prerequisites (delegation must carry escalation_requirements) and what the caller gets back. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that the confirmation is bound to action_details via hash and that scope determines which inputs matter (e.g. session_id for per_session). That is semantics the schema only gestures at.

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 artifact: the owner signs an OwnerConfirmation authorizing a flagged action, built and signed in one call. That is far more specific than siblings like request_human_approval or aps_check_escalation_required, though the description never names those siblings to disambiguate the escalation workflow.

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?

'Escalation boundary' implies this is used once an action has been flagged as requiring escalation, but it never states the precondition explicitly or points to aps_check_escalation_required as the tool that determines whether escalation is needed. Usage is inferable rather than 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?

Annotations already declare the safety profile (readOnly, non-destructive, idempotent, closed-world), and the description adds non-obvious semantics on top: the verification consequence of omission and the key-binding rule that the signature is checked against the key the receipt carries for that party and must be the key that party's DID commits to. That is genuine added context about authorization/key requirements. It does not describe what is returned or how failures surface, which keeps it from a 5, but nothing here contradicts the annotations.

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

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

Three tight sentences, front-loaded with the action, then the downstream consequence, then the cryptographic check — each sentence carries information. The only drag is the abstract 'Representation boundary:' opener, which is jargon an agent may not resolve, slightly delaying the concrete verb.

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?

Complexity is moderate (key-bound signing inside an attribution/consent framework) and there is no output schema, so the description should ideally say what comes back (a signed receipt vs. a bare signature) and whether the receipt is mutated. It covers purpose, precondition, consequence and the validation rule well, but the return-value gap is a real omission for a tool with no output schema.

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 a constraint the schema does not: the supplied private key must be the key the receipt carries for that party and the one the party's DID commits to, which governs key selection. It also ties the 'receipt' parameter back to aps_create_attribution_receipt in the schema. Format/error details for the key parameter are still absent.

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 actor (the cited principal), action (adds their consent signature) and object (an AttributionReceipt), so the tool's function is unambiguous. It also indirectly separates itself from siblings by naming the two consumers (verifyAttributionConsent, checkArtifactCitations) rather than restating its own name. It stops short of an explicit 'use this instead of X' contrast with the sibling signing/receipt tools, which is why it is not 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?

It gives clear context for calling: without this signature the downstream verifiers reject the receipt, which tells the agent exactly why and when this step is required. There are no explicit exclusions or alternative-routing statements (e.g. relative to aps_create_attribution_receipt or aps_check_projection_consistency), so it matches the 'clear context, no exclusions' band rather than a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the failure mode for self-certifying identifiers ('refused as unresolved rather than assumed'), the expiry check, and an explicit statement of what a valid result does and does not prove. It also gives the return shape, {valid, reason?}.

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?

Front-loaded with the core action and tightly written at roughly five sentences with no filler. The opening 'Representation boundary:' label is jargon-heavy relative to the plain statements that follow, costing a little immediate clarity.

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 correctly supplies the return shape and the trust boundaries an agent needs to interpret a result. The only material omission is any guidance on the optional `now` parameter and the semantics of the `reason` field when valid is false.

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 and the baseline is 3. The description adds the internal fields of the receipt that get validated (id, citer signature, consent signature, expiry), but never explains the optional `now` timestamp used to pin the evaluation moment.

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 — 'verify an AttributionReceipt end-to-end' — and enumerates exactly what is checked (id, citer signature, consent signature, expiry). The 'representation boundary' framing and the explicit non-guarantees cleanly separate this from related siblings like aps_verify_attribution_projection and aps_verify_attribution_primitive.

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 sets a semantic scope ('what it does not establish: that either party is authorized for your relying-party decision') which implies the tool should not be used as an authorization check, but it never names an alternative tool or states a when-to-use trigger. Usage is inferable rather than instructed, and the many similarly named aps_verify_* siblings are not disambiguated.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail: it internally constructs projections for all four axes before verifying, which an agent would not infer from the schema. It omits failure modes and return behavior, keeping it out of 5 territory.

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 written sentences, front-loaded with the core action and followed by the mechanism and use cases. No filler; 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?

For a two-parameter read-only verification tool with full schema coverage and no output schema, the description is nearly complete. The only gap is that with no output schema it could hint at what verification produces (pass/fail or per-axis results), but this is a minor omission.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only the nuance that the primitive is 'full' (all four axes), and says nothing about the issuer_public_key parameter or expected formats beyond what the schema already states.

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 ('verify of a full AttributionPrimitive') and clarifies the mechanism (constructs projections for all four axes and verifies each). This implicitly separates it from the sibling aps_verify_attribution_projection, which handles a single axis, 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?

Gives two concrete usage contexts: a post-construction sanity check, and verifying a primitive received from a peer. It stops short of explicit when-not-to-use or naming the projection-level alternative, but the scenarios are clear enough to route an agent.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the exact return shape and the enumerated failure reasons, plus the fact that verification is local and offline. It does not mention permission or key-trust requirements, but the added behavioral detail is substantial.

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, front-loaded with the operation and scope, then the return contract, then the locality constraint. Every sentence earns its place with no redundancy.

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 correctly carries the return-value burden by listing valid/reason outcomes, and annotations cover safety. Combined with full schema coverage, an agent has what it needs; only explicit prerequisite/auth details are 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. The description adds only marginal semantics ('single-axis' for projection, Ed25519 for the key), which the schema largely supplies. Baseline 3 is appropriate 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?

States a specific verb+resource (verify an AttributionProjection) and narrows scope with 'single-axis' and 'under the issuer's Ed25519 public key'. This distinguishes it from sibling verifiers like aps_verify_attribution_primitive and aps_check_projection_consistency, 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?

'Verification is purely local and needs no other axes' gives a contextual hint about prerequisites (no cross-axis data needed), but there is no explicit when-to-use guidance or routing to alternatives such as aps_verify_attribution_primitive or aps_check_projection_consistency. Usage is implied rather than 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?

Annotations already establish readOnly, idempotent, non-destructive behavior, so the bar is lower. The description usefully discloses the semantic scope of the verification (policy_reference match, signer membership, threshold, signature, max_time_to_promote, tamper check), but says nothing about failure behavior, whether it raises or returns a verdict, or any auth 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?

A single front-loaded sentence with a parenthetical check list; no sentence is wasted. The dense parenthetical is information-rich but pushes the leading 'Commitment boundary' jargon ahead of the actual action.

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 return contract (boolean verdict vs. exception) is left unspecified, which is a real gap for a verification tool. Otherwise the description covers inputs, checks, and the read-only nature sufficiently 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 coverage is 100% and the two parameters are already documented, giving a baseline of 3. The description adds genuine meaning by naming the policy sub-fields that are actually evaluated (required_signers, threshold, max_time_to_promote), telling the agent what must be populated in the policy object.

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 precise verb+resource (verify a promoted statement's PromotionEvent against a PromotionPolicy) and enumerates the exact checks performed, which functionally separates it from aps_promote_statement and review_promotion. It stops short of naming any sibling, so an agent must infer the routing from the check list 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 'Commitment boundary' framing implies this is a gate that runs after promotion, but the description never states when to call it, what precondition (a completed promotion) is required, or why one would choose it over review_promotion. Usage is only implied.

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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real value by naming the S1-S5 check set, flagging S3 conservation as the strongest invariant, and disclosing the return contract ({valid: true} or {valid: false, reason, detail}). It stops short of noting failure semantics like error vs invalid result, but this is a solid addition.

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, front-loaded with the core verify action and its checks, then the invariant rationale, then the return/optional-param facts. No filler, though the invariant sentence is marginally verbose.

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 compensates by stating the return shape and the S1-S5 verification scope, and by clarifying the optional cross-check path. It leaves no major gap for calling the tool correctly, though failure-mode specifics (e.g., malformed record handling) are absent.

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 explaining the functional consequence of supplying input_receipts (S5 cross-check plus individual receipt verification) rather than just restating the field. gateway_public_key and record semantics stay purely in the schema.

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

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

States a specific verb (Verify) and resource (signed SettlementRecord) and enumerates the checks performed (signature, Merkle roots, conservation, residual shape, input-receipts cross-check). This clearly separates it from siblings like generate_settlement and aps_aggregate_settlement that produce rather than validate settlements.

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

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

The description gives one conditional usage cue ('Pass inputReceipts to also recompute input_receipts_hash') but never states when to reach for this tool versus generate_settlement/aps_aggregate_settlement, nor any when-not conditions. Usage is implied rather than spelled out.

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?

The description asserts a state-changing action ('author withdraws their own provisional statement') and a signed withdrawal payload, while the annotations declare readOnlyHint=true (no environment modification). A withdrawal changes the statement's status, so the structured safety hint and the prose conflict. The added commitment-boundary and author-signature context is useful, but the contradiction is disqualifying.

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, front-loading boundary semantics, then the promotion exclusion, then the signing requirement. Every clause carries information, though the jargon opener 'Commitment boundary:' is slightly opaque as a lead.

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?

Covers the action, the author-only precondition, the promotion exclusion, and the signing payload – most of what is needed for a 3-parameter tool. With no output schema and a contradicted annotation, it still leaves the tool's actual effect (persisted withdrawal vs. returned artifact) and return value unspecified.

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 three parameters are already documented and the baseline is 3. The description earns a bump by stating who must sign (the author) and the exact payload to canonicalize (canonicalize({action:'withdraw', statement_id})), details absent from the schema's generic 'Hex Ed25519 signature' text.

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?

Names a specific verb (withdraw) and resource (provisional statement), scopes it to the author's own statement, and draws a line against promotion with 'already-promoted statements cannot be withdrawn.' An agent can distinguish it from aps_promote_statement, though that sibling is not 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?

Gives a clear precondition (caller must be the author) and an explicit when-not condition (promoted statements cannot be withdrawn). It stops short of naming the alternative tool to use when withdrawal is not applicable, so routing to siblings is left 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?

Annotations declare write/non-idempotent/non-destructive, so the safety profile is already covered. The description adds two genuinely useful traits beyond that: the [OPERATOR] tag signals an elevated authorization requirement, and 'Creates a delegation automatically' discloses a non-obvious side effect that a caller would otherwise not anticipate from the name.

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 with the authorization marker and the core action front-loaded. No filler, though the bracketed prefix is slightly cryptic without explanation.

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 mutation with no output schema, the description covers purpose and the auto-delegation side effect but omits what the tool returns, whether spend_limit caps are enforced, and the exact privilege implied by [OPERATOR]. Adequate but leaves real gaps an agent must infer.

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 all six parameters (task_id, role, agent_id, agent_public_key, scope, spend_limit) are documented in the schema. The description adds no syntax, format, or default detail beyond the schema, 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?

States a specific verb+resource ('assign an agent to a role in a task') and adds the automatic-delegation side effect. It is distinguishable from siblings like create_delegation because it frames delegation as a consequence of role assignment rather than the primary action, though it does not explicitly say when to prefer this over create_delegation.

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, prerequisites, or alternative guidance. The [OPERATOR] prefix hints at a privilege requirement but the description never states the condition that selects this tool versus create_delegation, create_v2_delegation, or accept_assignment.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the meaningful constraint that the floor must already be 'loaded' and that the attestation represents agent agreement, but it says nothing about what happens on a floor_version mismatch, whether the attestation is persisted, or whether extensions alter the commitment.

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 well-formed sentence with the action front-loaded and zero filler; it is appropriately short for a two-parameter tool. It stops just short of packing in the prerequisite information that would make the brevity fully effective.

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 governance-commitment tool with no output schema, so the description is the only place the agent can learn what the attestation actually produces and what it commits to. It omits the prerequisite relationship to load_values_floor, the consequence of attesting, and whether extensions broaden the commitment — gaps that matter for a values-floor attestation.

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 floor_version and extensions are already documented in the schema and this is the baseline case. The description adds no extra semantics such as whether floor_version must match the currently loaded floor or what a valid extensions string references.

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?

Names a specific verb ('Attest') and resource ('Values Floor'), and the object clause ('that your agent agrees to abide by') makes the commitment semantics clear rather than tautological. It is distinguishable from load_values_floor in principle, but it never explicitly contrasts the two, so an agent must infer the division of labour from the names 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?

There is no when-to-use guidance, no sequencing hint beyond the adjective 'loaded', and no named alternative. With siblings like load_values_floor, sign_charter, and create_disclosure in the same governance family, the description should state whether the floor must be loaded first and whether attestation is required before other calls.

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

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

Annotations already declare the mutation profile (readOnly=false, idempotent=false, destructive=false, openWorld=false), so the safety picture is covered. The description adds one useful behavioral fact beyond that — the message is 'signed' — but says nothing about required signing keys, delivery guarantees, or the persistence role of comms/broadcast.json.

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 sentence with zero filler, front-loading the action and the destination. Nothing is repeated from the title and nothing is padded.

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 non-idempotent broadcast mutation with five parameters, no output schema, and a nested data object, the description leaves open what 'signed' entails, how recipients are enumerated, and what success or failure looks like. It is minimally adequate but not complete for the tool's 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 100%, so each of the five parameters (subject, message, type, priority, data) is already documented in the schema. The description contributes no additional parameter semantics such as format expectations for subject or the priority ordering, so the baseline of 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 (send) and resource (a signed message), and the phrase 'to all agents' scopes it as a broadcast rather than a point-to-point send. It stops short of naming the siblings that overlap most (send_message, post_agora_message), so sibling 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 or when-not-to-use guidance and no named alternative, despite several competing messaging tools in the sibling list (send_message, post_agora_message, check_messages). The implied selection rule ('all agents' = broadcast, singular = send_message) must be inferred by the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the useful nuance that this is a hypothetical evaluation ('would violate'), implying a pre-check that does not consume access, but it says nothing about the response shape or what to do on violation.

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 zero waste. It is efficient, though for a 9-parameter tool this brevity borders on under-specification rather than pure 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 no output schema, 9 undocumented parameters, and only a one-line description, the definition is far too thin. An agent cannot know what inputs mean, what a violation result looks like, or how the limits interact.

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 9 parameters (6 required), and the description adds no parameter meaning whatsoever. Fields like windowStartMs, burstLimit, and maxAccessesPerWindow are left entirely for the agent to guess, which is a serious gap for a constraint-checking tool.

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 ('Check') and resource ('aggregate rate limits' on data access), making the intent clear. However, it does not differentiate this tool from the many similar check_* siblings (check_usage_permitted, check_combination_permitted, check_purpose_permitted), so an agent must infer which check applies.

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 prerequisites, and no mention of alternatives among the numerous check_* siblings. The agent is left to infer that this is a pre-access gate, 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful regulatory context (HIPAA, COPPA, GDPR Art 9) but says nothing about what a denial looks like or what the caller should do on failure, and there is no output schema to carry that.

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 with zero waste, and the core action is front-loaded before the regulatory rationale. Well-sized for what it chooses to say, even though it omits needed 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?

A 6-parameter compliance-checking tool with 0% schema coverage and no output schema needs the description to explain both the inputs and the meaning of a permitted/denied result. Neither is present, leaving the agent unable to correctly populate most arguments.

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 6 parameters, so the description carries the full burden of explaining them, and it adds nothing. Fields like reason, regulatoryBasis, forbiddenSourceIds, and forbiddenSourceClasses are entirely opaque; only the vague 'two sources' hints at otherSourceId.

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 if combining data from two sources is permitted.' The 'combining data from two sources' framing reasonably distinguishes it from siblings like check_purpose_permitted and check_retention_expired, 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, no prerequisites, and no mention of the closely related check_purpose_permitted / check_usage_permitted siblings. The agent must infer that this applies specifically to cross-source inferences from the purpose statement alone.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the jurisdiction-constraint vocabulary but says nothing about the outcome shape (permitted/denied), what the constraint strings mean, or whether a denial is blocking. Modest added value over annotations, hence a 3.

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 padding. It is efficient, though the parenthetical token list would be more useful tied to the transferConstraints parameter.

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 5-parameter compliance-check tool with no output schema and 40% schema coverage, the description omits the decision semantics an agent most needs: which constraints are honored, how the three required params interact, and what a permitted vs. denied result means. Adequate as a label, insufficient as an invocation guide.

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 only 40%: sourceJurisdiction and targetJurisdiction carry ISO 3166-1 alpha-2 descriptions, but purpose, transferConstraints and processingRestrictions are bare. The description names three constraint tokens that do not even map to a documented enum on transferConstraints, so it neither documents the params nor compensates for the coverage gap.

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+resource: checking whether a data transfer is permitted under jurisdiction constraints, and names the constraint vocabulary (EU_ONLY, GDPR_ADEQUATE_ONLY, NO_CROSS_BORDER). It does not, however, explicitly distinguish itself from the many sibling checks (check_purpose_permitted, check_combination_permitted, check_usage_permitted), so an agent must infer the split.

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, when-not-to-use, or alternative routing is given. The agent is not told whether this belongs in a pre-transfer gate, whether it should be paired with check_purpose_permitted or check_combination_permitted, or what to do when the check fails.

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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds real value by revealing the per-agent file backing store, but it never explains that the default invocation is a read while mark_read mutates persisted state, nor how reads are scoped per agent name.

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 with no filler; the purpose is front-loaded and the storage location follows immediately as supporting detail. 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?

For a two-boolean, zero-required-parameter tool this is close to adequate, and the file path hints at the payload. But with no output schema, the description says nothing about the returned message shape or fields, which is the main 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 carry their own descriptions and defaults, so the schema does the heavy lifting. The description adds no syntax, default, or interaction detail (e.g., that mark_read only affects the messages returned) beyond what is already structured.

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 and resource ('check messages') and scopes it with 'addressed to you,' which separates it from write-side siblings like send_message and broadcast. It also names the backing store (comms/to-{your-agent-name}.json), so the agent knows exactly what is being read. It stops short of explicitly naming an alternative tool.

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 call this versus send_message, broadcast, or the agora tools, and no guidance on how mark_read interacts with a typical check cycle. The only usage signal is the implicit 'messages addressed to you' scope, leaving the agent to infer everything else.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered by structured data. The description adds genuine behavioral context beyond that: wildcard support ('research:*') and hierarchical matching, which tells the agent how the comparison actually behaves. It stops short of describing return/error semantics.

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, no filler, with the core predicate stated first and the matching behavior second. Every sentence earns its place.

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

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

For a two-parameter, read-only predicate tool with fully documented parameters and annotations covering the safety profile, the description is nearly sufficient. The one gap is that no output schema exists, so the return shape (presumably a boolean plus rationale) is left for the agent to guess.

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 baseline is 3, and the schema already gives examples for 'purpose'. The description adds matching semantics (wildcards, hierarchical matching) that govern how the two string inputs are compared, which is meaning the schema alone does not convey.

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 if a purpose is permitted under source terms', which is clear and actionable. It does not, however, differentiate itself from near-name siblings such as check_usage_permitted or check_combination_permitted, so an agent lacks an explicit disambiguation signal.

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 'under source terms' implies the scenario (validating a requested purpose against a rights/terms list), so usage is inferable. But there is no explicit when-to-use, no when-not-to-use, and no routing to the many sibling 'check_*' tools that an agent must choose between.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the decision basis (TTL policy) and says nothing about boundary behavior such as how an expired result is determined or how the null max-retention case is treated — mild added value against a low bar.

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, which is efficient. It is arguably too terse given the surrounding gaps, but there is no wasted prose.

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 should clarify the return value and the significance of the null retention case, and it does neither. Annotations cover the safety profile and the schema covers most inputs, so the description is adequate but leaves an agent guessing about the result shape.

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 67%: accessedAt and maxRetentionMs are described in the schema, but the accessType enum (ephemeral/persistent) has no description anywhere. The description contributes no parameter-level meaning and does not compensate for the undocumented enum, though it does not mislead 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 specific verb (check) and resource (data retention expiry) and names the decision basis (TTL policy), so the agent can tell what the tool computes. It does not differentiate itself from the cluster of adjacent checkers like validate_temporal_rights or is_evidence_fresh, which is why it stops short of a 5.

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

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

The description gives no when-to-use guidance, no prerequisites, and no exclusions relative to the many sibling check_* tools. The usage is only implied by the tool name; nothing tells the agent when retention checking is the right call versus a temporal-rights or freshness check.

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