Physical Capability Cloud

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the state-changing-but-non-destructive profile is covered. The description usefully specifies the resulting state (equipment live, accepting jobs), but says nothing about idempotency, whether activation is reversible, or permission requirements.

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

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

A single front-loaded sentence that states the action and its consequence with no filler or repetition of the tool name.

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

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

For a simple one-parameter mutation with no output schema and annotations covering the safety profile, the description covers the essential effect. It could go further on prerequisites and reversibility, but nothing critical to invoking it is missing.

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

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

Only one parameter and schema coverage is 100%, so the schema already fully documents registrationId. The description adds only the implicit constraint that it must reference an approved registration; baseline 3 applies when the schema carries the parameter definition.

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

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

Specific verb (activate) plus resource (approved registration) and a concrete outcome — the operator's equipment goes live and can accept jobs. The word 'approved' implicitly separates it from approve_registration and reject_registration, but 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?

The prerequisite that the registration must already be approved is implied by the adjective 'approved', which gives some usage context. There is no explicit when-to-use vs. alternatives guidance, nor any statement of when activation should not 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?

Annotations only declare readOnlyHint=false and destructiveHint=false, leaving the description to carry the semantics. It does so by disclosing the ordered state progression (implying a directional, non-destructive state transition) and an entry precondition (sufficient training episodes). It still omits whether the advance is one step or to a target level and behavior on 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?

Two compact sentences, front-loaded with the action and the state ladder, then the gating condition. No filler or 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?

For a mutation tool with no output schema and fully-documented params, the description covers the action, the ordered states, and the precondition. The main residual gap is ambiguity about whether one call advances a single step or transitions to a chosen level, which matters 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 100%, so fromNodeId and toNodeId are already documented. The description adds the concept of the automation ladder but never ties it to either parameter (no target-level parameter is mentioned), so it contributes only marginal meaning beyond the schema. 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?

Names a specific verb ('advance') and resource ('automation level for a transfer pair'), and enumerates the full state ladder (manual → ... → fully_autonomous), which strongly disambiguates it from neighbors like get_automation_status. It does not explicitly name or rule out any sibling, but the level ladder makes the operation's identity unmistakable.

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?

'Requires sufficient training episodes' is a genuine precondition, which implies when the call is appropriate. However, there is no guidance on when to use this versus get_automation_status or list_automation_status, and no statement of what happens if the precondition is unmet.

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 and destructiveHint=false, so safety is partly covered and the description's 'upload docs' wording is consistent with a non-read-only but non-destructive operation. The description adds the returned artifacts, but says nothing about whether an analysis record is persisted, what the document reference format is, or any cost/latency.

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 what the tool is before what it returns. No filler, though the output list is compressed into one comma run.

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, listing the returned artifacts is genuinely useful and partially compensates. However, for a single-parameter tool whose schema marks 'document' as optional (required: []), the description implies upload is necessary without reconciling that, and leaves persistence/return format 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% for the single 'document' parameter, so the schema already explains it as 'content or reference'. 'Upload docs' in the description reinforces the intent but adds no syntax, format, or size guidance beyond the schema. 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 resource ('machine documentation') and an analysis action, and enumerates the outputs (suggested capabilities, specs, materials, tolerances), which makes the function concrete. It does not, however, distinguish itself from adjacent siblings like onboard_machine or create_capability, which could plausibly consume similar inputs.

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 or when-not-to-use guidance, and no alternatives are named despite a large sibling set. 'Upload docs to get...' implies the input shape but not the conditions under which this tool is the right choice.

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

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

Annotations already declare it is a non-read-only, non-destructive mutation. The description adds substantive behavioral context beyond that: the precise state machine transition (submitted -> approved) and the downstream consequence (operator can activate and accept jobs). It omits reversibility, permissions, and failure modes, but the transition semantics are genuinely informative.

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 action and followed by the state transition and consequence. No filler or 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?

For a one-parameter mutation with no output schema and annotations covering the safety profile, the description supplies the key missing context: what state the resource must be in and what approval unlocks. It could optionally note the read counterpart (get_registration) or whether the action is reversible, but nothing essential for calling it is 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 description coverage is 100% and the single registrationId parameter is already documented with a format example ('reg-1234567890'). The description adds no further meaning about the identifier, 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 (approve) and resource (submitted machine registration) and describes the exact state transition from 'submitted' to 'approved'. It also distinguishes itself from the nearby siblings activate_registration and reject_registration by framing approval as the precondition that enables activation.

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?

Clear context for when this applies: the registration must be in 'submitted' state, and the outcome enables the operator to activate. It does not state explicit exclusions (e.g. what to do instead when rejecting or when the registration is already approved), 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 declare readOnlyHint=false and destructiveHint=false, so the mutation safety profile is covered. The description adds real behavioral value beyond that: it discloses idempotency and that an existing CID is returned on repeat calls, which prevents redundant archiving.

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 primary action and effect, followed by the idempotency behavior. No filler or 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?

For a single-parameter mutation tool with annotations covering safety and an inferred CID return value, the description covers action, destination, persistence, and idempotency. Only the absence of prerequisite/auth context keeps it short of complete.

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% with a single well-documented bundleId parameter, so baseline 3 applies. The description adds no format or syntax detail beyond what the schema already provides.

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 (archive) with a specific resource (encrypted evidence bundle), the destination (IPFS), and the side effect (store CID in database). Distinguishes the operation well, though it does not explicitly differentiate from the sibling archive_evidence.

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 guidance on when to use this tool versus the many sibling evidence tools (archive_evidence, commit_evidence, register_job_evidence_ip). The idempotency note hints at safe re-invocation but says nothing about prerequisites or alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds that storage is permanent/decentralized and that the operation returns a content-addressed CID, which is useful context 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 tightly written sentences with the action and destination front-loaded. 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?

The description covers the operation, destination, permanence, and return value, but the input schema exposes only an opaque nested object for 'bundle' with no shape guidance. For a write tool with a required nested object, this leaves a meaningful gap 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 single 'bundle' parameter is described in the schema as an evidence bundle object. The description does not add any further parameter meaning, 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?

The description gives a specific verb and resource ('Archive an evidence bundle') plus the destination ('IPFS/Storacha for permanent decentralized storage'). It does not differentiate from the sibling 'archive_encrypted_bundle', 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?

No when-to-use guidance, prerequisites, or alternatives are given. The existence of siblings like 'archive_encrypted_bundle' and 'commit_evidence' makes this gap meaningful.

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 (readOnlyHint=false, destructiveHint=false) already establish a non-destructive write. The description adds real context beyond that: it returns the channel record with a generated id, PCC stays transport-neutral, and vendor specifics belong in the free-form describe field. It does not cover permissions/auth prerequisites, but with annotations present the bar is lower.

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 that lead with the action, then the lifecycle timing, then the transport/describe contract. The only slightly expendable line is 'PCC the substrate stays neutral,' which is flavor more than instruction but still short.

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?

Handles a 9-parameter, nested-object tool well: the caller knows what it does, when to call it, what it returns, and how the enum vs. free-form fields divide responsibility. No output schema exists, yet the return shape (channel record with generated id) is stated; missing only auth/error behavior details.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the design intent of describe (vendor specifics authored by the operator's agent) and the small stable transport enum while explicitly contrasting it with the free-form field. That adds interpretive value the schema text alone does not.

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

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

States a specific verb (attach) and resource (notification/dispatch channel to an operator) plus the rationale (so PCC can ping them when a job lands). This clearly separates it from list_operator_channels, update_operator_channel and delete_operator_channel. It never names a sibling explicitly, so it stops just short of the top score.

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 concrete timing guidance: 'The operator's onboarding agent calls this AFTER the conversation that produced the channel record.' That tells the agent when in the lifecycle to call it, but there is no explicit when-not or pointer to an alternative (e.g. update_operator_channel for existing records).

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 signal a non-read-only, non-destructive write. The description adds that submission happens and escrow is involved, but omits consequential behavior: whether funds are locked at this step, auth/bond requirements, and irreversibility of the milestone escrow. Some added context, but significant gaps remain for a mutation.

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

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

Two tight sentences with zero filler, front-loading the action and following with the return values. 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 4-param mutation with a nested 'selections' object and no output schema, the description helpfully states the return values (job ID and escrow address), partially compensating for the missing output schema. However it leaves prerequisites, escrow-funding implications, and the relationship to sibling escrow tools 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 description coverage is 100%, so all four parameters are already documented (including assuranceTier's 0-3 semantics). The description adds no parameter-level meaning beyond the schema, 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 compound verb (build and submit) and resource (capability contract) plus the key mechanism (on-chain milestone escrow). It is clear what the tool produces, though it does not explicitly distinguish itself from near siblings like create_capability, protocol_create_escrow, or fund_escrow.

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 (e.g. must a capability/profile exist first), and no routing to alternatives such as create_capability or fund_escrow. The agent must infer placement from the 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 declare destructiveHint=false but readOnlyHint=false, which is mildly surprising for a pure calculation and is neither explained nor reconciled. The description does add value by disclosing the returned components (base price, tier premiums, total), which matters since there is no output schema, but it omits side effects, permissions, and caching behavior.

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

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

Two tightly written sentences with the purpose front-loaded and the return contents second; no filler and nothing that could be cut without losing information.

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

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

With no output schema, the description appropriately explains what is returned, and the fully documented schema covers the inputs. The main remaining gap is the unresolved readOnlyHint=false signal for what reads like a side-effect-free calculation.

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 type, profileId, and selections (including the nested material/dimensions/quantity fields). The description adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Calculate price for a capability configuration') and is clearly distinct from calculation siblings such as calculate_roi. It does not explicitly differentiate itself from adjacent quote/fee tools like pcc.op.capability.request_quote or protocol_fee, so sibling routing 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 when-to-use or when-not-to-use guidance and no named alternative, even though the sibling list contains several pricing/quote/fee tools (calculate_roi, request_quote, protocol_fee, pcc_protocol_fee) that an agent must choose between. Prerequisites for calling it are also unstated.

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 readOnlyHint=false and destructiveHint=false, so the safety profile is partly covered, though the non-read-only flag is unexplained for something that reads as a pure computation. The description adds useful behavioral detail by disclosing the response shape (month-by-month revenue, cost, break-even), which matters since there is no output schema.

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, both earning their place: the first states purpose, the second states output. Front-loaded and free of 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?

The description compensates for the missing output schema by summarizing returns, and all params are documented in the schema. However, it omits what happens when the optional parameters are omitted (defaults), and gives no usage context, leaving a gap for a projection tool with zero required inputs.

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 three parameters (avgJobValue, monthlyCost, utilization) are already documented in the schema. The description adds no parameter-level meaning, making the baseline 3 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 ('Calculate ROI projection') plus the domain ('for onboarding equipment'), so the agent knows what the tool produces. It does not explicitly distinguish itself from the nearby sibling calculate_price, so it falls just 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 phrase 'for onboarding equipment' implies the usage context, but there is no explicit when-to-use statement, no exclusions, and no named alternative (e.g. calculate_price). Usage is only inferable from the domain wording.

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 and destructiveHint=false, so safety is covered, and the description adds real behavioral context by disclosing the terminal-state constraint on cancellation. It stops short of saying whether cancellation is reversible, idempotent, or permission-gated.

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

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

Two short sentences, front-loaded with the action and followed immediately by the constraint. Every clause earns its place with 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?

For a single-parameter mutation tool with no output schema, the action and its precondition are sufficient to invoke it correctly. A brief note on the effect of a successful cancellation (state transition, return value) would close the remaining gap.

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

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

There is only one parameter and schema coverage is 100%, with the schema describing it as 'Protocol run ID to cancel'. The description adds no format, naming, or sourcing detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (cancel a protocol run), which is unambiguous on its own. However, it does nothing to distinguish itself from close siblings like pause_protocol_run, resume_protocol_run, or start_protocol_run that operate on the same resource.

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 second sentence gives a useful precondition (not completed, not already cancelled), which implies when not to call it. But it never names an alternative action or tells the agent how cancellation differs from pausing, so routing between the lifecycle siblings remains guesswork.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine value by disclosing the return shape ('whether the code is valid and what it includes'), which matters since there is no output schema.

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: the action first, then the return value. No redundancy or filler.

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

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

For a single-parameter read-only tool with annotations covering the safety profile and the description covering the return, the definition is nearly complete. The only gap is not naming the redeeming tool as the follow-up alternative.

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?

With a single parameter at 100% schema description coverage, the schema already documents 'code' as the invite code to check. The description adds no format, syntax, or length detail beyond that, 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 ('Validate') and resource ('invite code') and situates it in a workflow ('before redeeming it'). It clearly signals a pre-redemption check, but does not name the sibling redeem_invite outright.

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 'before redeeming it' implies when to use this tool versus redeeming directly, which is useful. However, it never explicitly names the alternative tool (redeem_invite) or states when NOT to use it, leaving the routing partly 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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the return payload is all threads for the kernel plus a hasUnreadReplies boolean, which is important for a polling tool with no output schema.

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 with no filler: purpose first, then the trigger condition, then the return shape. 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 single-param read-only poller with no output schema, the description covers purpose, trigger, and the key return fields. It stops short of describing thread structure or ordering, but nothing essential to calling it correctly is missing.

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

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

Only one parameter with 100% schema description coverage ('Operator's kernel ID'), so the schema carries the load. The description reinforces the scoping ('all threads for this kernel') but adds no syntax or format detail beyond the schema, matching the baseline 3.

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 ('admin replies on the operator's support threads'), and implicitly scopes to 'this kernel'. An agent can distinguish it from send_support_message and reply_to_support_thread, which are the write-side siblings in the same domain.

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 explicit trigger conditions: 'Call this periodically or when the operator asks did they respond yet?'. This is clear context for invocation, though it names no exclusions or alternative tools (e.g. list_conversations) for related lookups.

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 a non-destructive mutation (readOnlyHint=false, destructiveHint=false). The description adds meaningful obligation context, that the operator commits to registering the capability and completing verification, but it doesn't state whether the claim is exclusive, what happens on failure to complete, or what the response signals.

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 the action front-loaded and the commitment detail second. No wasted text, though it could arguably say more given the surrounding ecosystem.

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

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

For a mutation tool with no output schema, the description covers what it does and the operator's obligation but omits prerequisites (bounty availability, how to find bountyId via list_bounties) and post-claim state. Annotations cover the safety profile, so this is adequate rather than complete.

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%, with both bountyId and operatorId clearly documented, so the schema carries the weight. The description adds no format, ID-source, or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb+resource ('claim a bounty') and adds purpose ('to onboard a new capability'), which distinguishes it from read-side siblings like list_bounties. It doesn't explicitly contrast itself with verify_bounty or convert_bounty_to_pool, so it stops short of full sibling differentiation.

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 stated goal of onboarding a capability, but there is no explicit when-to-use or when-not-to-use guidance, and no prerequisite (e.g. that the bounty must be listed/available, or how this relates to verify_bounty). The agent must infer the trigger 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?

Annotations mark it non-read-only and non-destructive, and the description adds the return shape (claimed amount and transaction hash), which is useful context for a value transfer. But for a revenue-claim mutation it omits important traits: whether the action is on-chain/irreversible, gas or fee implications, and any auth requirements. With annotations covering only the safety flags, 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?

Two short sentences, both front-loaded: the action first, then the return value. No filler or 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?

For a financial/on-chain claim tool with no output schema, the description sensibly describes the return values in text. However, it is missing the usage routing against get_ip_revenue and any disclosure about irreversibility or fees, leaving an agent under-informed for a value-transfer operation.

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 ipId and tokenIds are already fully documented in the schema, including the 'claims all if omitted' behavior for tokenIds. The description adds no syntax, format, or constraint detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb ('Claim') and resource ('earned revenue from an IP asset vault'), which clearly separates it from the read-only sibling get_ip_revenue. However, it does not explicitly name get_ip_revenue or pay_ip_royalty, so the differentiation is implied rather than stated.

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 guidance on when to use this versus get_ip_revenue (the read counterpart), pay_ip_royalty, or distribute_royalties. No prerequisites such as ownership, vault state, or timing are mentioned.

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 readOnlyHint=false and destructiveHint=false, indicating a non-destructive mutation. The description adds the precondition 'after capability verification', which is meaningful context beyond annotations. However, it doesn't explain what the claim does (e.g., transfers tokens, marks as claimed), whether it's idempotent, or what authorization is needed. For a mutation tool, this is a significant gap.

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 that is concise and wastes no words. It efficiently conveys the core action and one precondition. It could arguably be slightly more informative, but it avoids verbosity.

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?

Given the tool is a non-destructive mutation with no output schema and annotations that only cover safety hints, the description is incomplete. It omits what happens on success (e.g., reward transferred, state updated), prerequisites (e.g., verification status), and error conditions. For a claim operation in a complex system with many siblings, this leaves too much 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 100% – both poolId and operatorId are documented in the schema. The description adds no parameter details beyond what the schema provides. Baseline 3 is appropriate when the schema fully documents parameters and the description doesn't compensate with extra semantics.

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+resource: 'claims an investment pool reward', which is clear and distinguishable from siblings like claim_bounty, claim_ip_revenue, and stake_in_pool. It doesn't explicitly name those alternatives, but the resource 'investment pool reward' is specific enough to disambiguate.

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

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

No when-to-use or when-not-to-use guidance is provided. It mentions 'after capability verification' as a precondition but doesn't explain how the agent should verify this, or what alternatives exist (e.g., stake_in_pool, get_pool_earnings). An agent would have to infer usage from context 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 declare readOnlyHint=false and destructiveHint=false, so the agent already knows this mutates state without destroying data. The description usefully confirms that effect is limited to new stakes and that the pool enters a 'sunset phase,' which resolves the ambiguity about whether existing stakes are wiped. It still omits reversibility, whether the operation can be undone, and any permission requirements, so it adds context but not rich behavioral detail.

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, zero filler, with the core action and its scope front-loaded before the state consequence. Nothing can be removed without losing 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 one-parameter mutation with annotations present and no output schema, the description covers the essential effect and the resulting state. It is adequate but leaves open what happens to existing stakes and whether the close is reversible, which an agent invoking an irreversible-looking lifecycle change might reasonably need.

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 (poolId) with 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about the parameter, which is the expected baseline when the schema does the work.

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 ('Close an investment pool') with a scope qualifier ('to new stakes'), which clearly distinguishes it from sibling mutations like stake_in_pool, claim_pool, and create_investment_pool. It does not name or contrast with any sibling explicitly, so it lands at 4 rather than 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 'to new stakes' implies the situation in which this tool applies (stopping new participation), but there is no explicit when-to-use guidance, no prerequisites (e.g., pool owner authority), and no exclusion or alternative named. Usage is inferable but not 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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write; the description is consistent with that. It adds no detail on side effects, idempotency, or whether reruns produce duplicate commitments.

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 that front-load the action, with the workflow positioning as supporting context. No filler.

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

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

For a single-parameter, non-destructive write tool this covers the essentials. With no output schema, it could mention what the commitment returns, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so bundleHash is fully documented in the schema. The description adds no format or semantic detail beyond what the schema already provides. 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 ('Create a Merkle commitment for an evidence bundle hash') and clarifies the input it operates on. It is distinguishable from siblings like submit_evidence_hash and verify_evidence_zk, though it does not name them 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 phrase 'first step in ZK proof generation for Tier 3 assurance' implies the workflow context and ordering, but no alternatives, prerequisites, or when-not-to-use conditions are given. 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 declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. However, the description says nothing about the most important behavior for a conversion: whether the bounty ceases to exist as a bounty, whether the action is reversible, or what authorization 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?

Two short sentences with the purpose front-loaded and no padding. The staking clause is slightly extraneous but does not derail the reader.

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 state-mutating conversion tool with no output schema and only weak annotation coverage, the description omits the outcome semantics (what the bounty becomes, what happens to existing claims/stakes) that an agent needs before invoking it.

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% with a single documented parameter, so the baseline is 3. The description adds no format, ID-source, or validation detail beyond what the schema already provides.

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 ('Convert an existing bounty into an investment pool'), which an agent can distinguish from create_investment_pool / create_pool since this one requires a pre-existing bounty. The trailing clause about community staking is vague but adds scope.

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

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

No explicit when-to-use guidance and no routing to alternatives. The word 'existing' implies a bounty must already be present, but the prerequisites (ownership, bounty state, whether it must be unclaimed/unverified) are left 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 readOnlyHint=false and destructiveHint=false, so mutability is covered. The description adds useful prerequisite semantics (at least one capability per kernel before job submission) but says nothing about idempotency, permissions, or what is returned after registration.

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

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

Three short sentences, front-loaded with the core action and then the critical prerequisite. The third sentence largely restates the schema's type enum examples, which is slightly redundant but not wasteful enough to hurt.

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

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

For a mutation tool with no output schema, the description covers the action, the essential prerequisite, and the nominal types. The notable remaining gap is that it never indicates what the call yields (e.g. a capability ID the agent would need later for job submission), which matters given the stated ordering dependency.

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% with 4 documented parameters, so the schema carries parameter meaning. The description's type examples duplicate the schema's own type description and add no format, constraint, or validation detail beyond it.

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

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

States a specific verb ('Register') and resource ('a capability instance for a kernel'), and the third sentence enumerates capability types, so the agent knows what gets created. It stops short of explicitly differentiating from near-siblings like register_capability_ip or kernel_announce_capabilities, which could be confused with it.

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?

Explicitly states the precondition and timing: 'Required before submitting jobs — the gateway needs at least one capability per kernel.' That is genuine when-to-use guidance an agent can act on, though it names no alternative tool or 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 declare readOnlyHint=false and destructiveHint=false, so the mutation/non-destructive profile is already covered. The description adds meaningful domain behavior—this is a funding vehicle where stakers accrue future protocol fees—but says nothing about permissions, whether the pool is mutable afterward, or what happens when a pool is created twice for the same capability.

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, action first, purpose second. No filler, no redundancy, and the key noun phrase is front-loaded.

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

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

For a 4-param mutation with no output schema and only partial behavioral annotation coverage, the description is adequate but thin. It omits prerequisites, duplicate-pool handling, and what a successful call yields; the schema covers parameters at 100% but does not compensate for behavioral gaps.

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

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

Schema description coverage is 100%, so all four parameters (currency, description, targetAmount, capabilityType) are already documented in the schema. The description adds no syntax, default, or format detail beyond it, which is the expected baseline 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 and resource ('Create an investment pool') plus the domain intent (funding a capability bounty, stakers earn future protocol fees). It is more than a restatement of the name. However, it does not distinguish itself from close cousins like convert_bounty_to_pool, stake_in_pool, or create_capability, so sibling differentiation is missing.

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 guidance on when to create a pool versus converting an existing bounty to a pool or staking into one, and no prerequisites (e.g., whether the capability must exist first). The agent gets domain context but no routing logic.

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 this is a write (readOnlyHint=false) that is non-destructive, so the safety profile is covered. The description adds the onboarding-flow positioning but says nothing about idempotency, required pre-existing state, or what registration produces.

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, zero waste, and the core action is front-loaded before the flow context. 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 create tool with three nested object parameters and no output schema, the description is minimal but adequate. It leaves unclear how config/location are consumed and what a successful registration returns, which matters more given the nested payloads.

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 schema already documents name, config, location, and description, and the description adds no syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Register a new Shop Kernel') and disambiguates the non-obvious term by equating a kernel with a 'physical site'. It clearly differs from the read siblings (get_kernel, list_kernels), though it never names a sibling 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?

Places the tool in a workflow context ('Step 2 in the onboarding flow'), which implies when to reach for it. However, it gives no prerequisites, no ordering details, and no statement of when NOT to use it or which sibling handles follow-up steps.

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 readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is already covered. The description usefully adds that the result is a 'draft' and that a template ID is returned, but says nothing about validation, required capabilities, or what happens to the arrays supplied.

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

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

Two tight sentences with the creation action front-loaded and the return value second. 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 7-parameter create tool with full schema coverage and no output schema, the description compensates by naming the returned ID. It is adequate to call the tool, though it omits lifecycle context (draft vs published) that would help sequencing.

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 seven parameters are documented in the schema itself. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a new protocol template draft') and adds the return value. The word 'draft' signals it is distinct from publish_protocol and update_protocol, though it does not explicitly name any sibling for contrast.

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

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

No when-to-use guidance, no prerequisites, and no alternatives named. The agent is left to infer from 'draft' that a separate publish step follows, but nothing states when to choose this over fork_protocol or create_protocol_run.

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 it is a write operation (readOnlyHint=false) that is not destructive, so the safety profile is covered. The description adds nothing beyond that: it does not say what side effects the run triggers, what permissions are needed, or whether the template defaults are mutated versus overridden (only implied via schema).

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 or redundancy. It is efficient, though the brevity comes at the cost of the details that would aid invocation.

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

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

This is a mutation tool with four parameters, a nested parameterValues object, and no output schema. The description never indicates what is returned (e.g., a run ID to feed into get_protocol_run / pause_protocol_run), nor what state the new run starts in, which is important context for a create-style tool.

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

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

Schema description coverage is 100%, so id, kernelId, sampleIds, and parameterValues are already documented in the schema. The description's phrase 'on a specific kernel with given parameter values' mirrors the schema without adding format or constraint detail, 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?

The description gives a specific verb (Instantiate) and resource (a protocol template as a run) plus a scope qualifier (on a specific kernel). It clearly states what is produced, but it does not distinguish itself from close siblings like start_protocol_run, create_protocol, or fork_protocol, leaving the agent to infer the boundary.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With a sibling literally named start_protocol_run, the absence of any routing rule is a real gap for 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=false and destructiveHint=false, so the write/safety profile is covered structurally. The description adds nothing beyond that: no permission requirements, no idempotency or duplicate-handling behavior, no statement of whether a provider must be registered, and no indication of what the call returns.

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 that front-loads the verb and resource and omits filler. It is efficient, though it wastes its brevity on restating parameter names instead of conveying routing or behavioral information.

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

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

For a mutation tool with nested objects, one required field, and no output schema, the definition is minimally adequate. It does not say what a successful creation yields (e.g., a shipment ID) or how it relates to the quote tool, which an agent would need for correct sequencing.

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 includes nested object descriptions, so the schema already carries parameter meaning. The description merely echoes the field list (origin, destination, package, provider) without adding format, constraint, or default details. 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?

Specific verb (Create) plus resource (equipment shipment) with an enumeration of the payload fields, which lets an agent distinguish it from read-side siblings like get_shipments and get_shipment_quote. It stops short of explicitly contrasting itself with 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?

No guidance on when to use this versus alternatives. Notably, get_shipment_quote and get_logistics_overview exist nearby, and the description never says whether a quote must be obtained first or when a shipment should be created directly. No prerequisites or preconditions are stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the downstream consequence ('Future jobs will not dispatch to it') and an implied permanence contrasted against temporary disabling. It stops short of stating irreversibility or auth requirements 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 short sentences, each earning its place: action, consequence, and alternative. The purpose is front-loaded 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 single-parameter destructive delete with annotations covering the safety profile and full schema coverage, this is complete: it conveys the effect, the permanence relative to disabling, and the sibling alternative. No output schema is needed.

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 id parameter, so the schema already documents it fully. The description adds no parameter-level detail (format, source, constraints). Baseline 3 is correct when the schema does all the work.

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 (Remove) and resource (channel from an operator), and distinguishes itself from the sibling update_operator_channel by naming it explicitly. An agent can tell what this does and what it is not without opening the 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?

Gives explicit when-to-use and when-not-to-use guidance, naming the alternative (update_operator_channel with enabled=false) and the condition that selects it (temporary silence without losing the recipe). This is exactly the routing information an agent needs.

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 and destructiveHint=false, so the mutation/safety profile is partly covered. The description adds that the bond is posted on-chain but omits permissions/token-approval prerequisites, whether the bond is refundable or slashable, and gas considerations — meaningful gaps for a value-transfer operation.

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

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

Three short sentences, front-loaded with the action and the requirement, with no filler. Every sentence carries distinct information (action, condition, return value).

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?

It helpfully states the return value (transaction hash) even though no output schema exists, and the annotations cover the safety profile. Still, for an on-chain mutation tool it leaves out prerequisites and bond lifecycle behavior, leaving the agent incompletely briefed.

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 (address, milestoneIndex) are already documented in the schema. The description adds no format, range, or 0-based indexing detail beyond what the schema already provides, 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 (Deposit) and resource (operator bond for a milestone) and specifies it happens on-chain. It does not, however, distinguish itself from nearby siblings such as fund_escrow, which an agent might reasonably confuse with it.

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 concrete usage condition: 'Required for Assurance Tier 3 jobs.' This tells the agent when the call is mandatory, but it names no alternatives and offers no when-not guidance, so it stops short of full routing clarity.

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 this is a non-read-only, non-destructive mutation, so the safety profile is partly covered. The description adds the significant eligibility restriction and the evidence requirement, but says nothing about what the dispute triggers afterwards (escalation, slashing, reversibility) or whether it is idempotent.

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, purpose front-loaded, no filler. Every sentence carries information, though the middle eligibility sentence could have been folded in without loss.

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

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

For a mutation tool with no output schema and fully documented parameters, the definition covers what is needed to call it, but leaves the outcome of a dispute (who resolves it, what happens to the consensus verdict or the disputer) unexplained.

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

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

Schema description coverage is 100%, so all four parameters (requestId, disputerId, reason, evidenceCid) are already documented. The description only amplifies the evidenceCid requirement with 'additional evidence CID' and adds no format or constraint details 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 (file) and a specific resource (dispute against the consensus verdict), which distinguishes it from the other dispute-family siblings like file_escrow_dispute and raise_ip_dispute. It is clear but never names those siblings to route the agent 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?

'Only verifiers who submitted a response can dispute' is an explicit eligibility precondition, which is more than most definitions offer. It does not, however, sketch when a dispute is preferable to alternatives such as respond_to_verification or submit_for_human_verification.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the mutation semantics are implied but not elaborated. The description does not say whether existing splits are overwritten, who is authorized to set them, whether the operation is reversible, or whether it emits a transaction — significant gaps for a write tool.

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

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

Two short sentences, zero filler, with the core action and the validity constraint front-loaded. 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?

Adequate minimum: the agent knows what to set and the sum constraint, and the schema covers all parameters. But for a mutation with no output schema and only minimal annotations, the description should cover authorization, overwrite behavior, and the effect on existing splits.

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 ipId and the nested split fields are already documented. The description's enumeration of roles and the sum-to-100 rule merely restates what the schema already encodes, adding no syntax or format detail beyond it.

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

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

States a specific verb and resource ('Set revenue splits for an IP asset') plus the stakeholder roles involved. It is distinguishable from read-side siblings like get_ip_revenue and pay_ip_royalty, though it never explicitly names which sibling 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?

No when-to-use, when-not-to-use, or prerequisite information. The agent cannot tell from the description whether this should be called at registration time, on an existing asset, or how it relates to pay_ip_royalty and claim_ip_revenue.

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 and destructiveHint=false, so the agent knows this is a non-destructive write; the description is consistent with that. It adds that the emission is manual and phase-scoped, but says nothing about persistence, idempotency, duplicate handling, or required authorization — meaningful gaps for a write tool.

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

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

Two short sentences, front-loaded with the core action and 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 7-parameter write tool with no output schema, the description covers purpose and audience but leaves out what happens on emission (persistence, confirmation, failure behavior) and any note that the optional fields (level, source, metadata, duration_ms) are optional. Adequate but with clear gaps.

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

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

Schema description coverage is 100% and both enums (level, status) are documented in the schema, so the baseline is 3. The description adds no syntax, default, or semantic detail beyond what the schema already provides.

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+scope: 'Manually emit a telemetry event for a job pipeline phase.' The word 'Manually' cleanly distinguishes it from the read-side siblings (get_job_telemetry, get_active_telemetry, get_telemetry_logs) and from automatic/system telemetry emission, so an agent can tell write-event from read-event without opening a 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 second sentence ('Used by kernels and agents to report execution progress') gives implied context on who calls it and why, but there is no explicit when-to-use vs when-not, no mention of alternatives (e.g. system_telemetry or send_diagnostics), and no stated prerequisites.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, but the description goes far beyond by disclosing flag-controlled real vs NOOP execution, durable workflow via @pcc/workflow, idempotent replay semantics, and exactly-once reputation deltas. This is rich behavioral context that an agent needs.

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 sentences front-load the core action and outcome, then cover flag behavior and idempotency. Every sentence carries relevant information, though some tightening is possible.

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

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

For a mutation tool with no output schema, the description covers execution semantics, environment flags, and idempotency well. It stops short of describing the return value (e.g., run id or status), which would be useful given the absence of an 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 description coverage is 100% and both parameters are documented in the schema (id with status precondition, idempotencyKey with length cap). The description adds no parameter-level syntax or format details beyond what the schema provides; 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 (commit a proposed composition) and describes downstream effects (drives DAG, records reputation outcomes, finalizes reputation). It implicitly distinguishes from propose_composition but never names it as an alternative in the description itself.

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

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

No explicit when-to-use guidance or alternatives. 'Commit a proposed composition' implies the context but does not state prerequisites (e.g., must be proposed and not expired), nor does it mention when not to use or what alternative tools exist.

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 readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is already given. The description adds real value by noting the challenger must post a bond (funds movement) and supply an evidence hash, but omits what happens to the bond on failure, whether the action is reversible, and any authorization requirements.

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

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

Three short sentences that are front-loaded with the action and then the requirements. No filler, though it is terse to the point of omitting useful routing and consequence information.

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

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

Five required params, no output schema, and a mutation with financial stake. The return value (transaction hash) is stated, which is helpful, but the description does not cover the dispute lifecycle or bond consequences, leaving gaps for a tool of this complexity.

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

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

Schema description coverage is 100% with all five params documented (address, milestoneIndex, challengerBond, challengerEvidenceHash, reason). The description restates bond and evidence hash at a high level but adds no format or unit 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 and resource: 'File a dispute against a milestone on-chain.' This is clear enough to distinguish it from read-side siblings like get_escrow_dispute and other dispute tools such as dispute_verification or raise_ip_dispute, though it does not explicitly contrast with them.

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

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

No when-to-use guidance, no prerequisites beyond the implied bond, and no routing to alternatives such as dispute_verification or raise_ip_dispute. The agent must infer context entirely from the name and required params.

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 readOnlyHint=false and destructiveHint=false, so safety profile is already covered. The description adds real value beyond that: it discloses the source-side effect ('Increments the source's fork counter') and the permission rule (public/unlisted any, private only if owned).

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 verb and lineage semantics, then use case, side effect, and permissions. Slightly dense with the em-dash aside and repeated 'fork' phrasing, but every sentence carries information.

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

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

Output schema exists, so return values need not be described. The description covers purpose, context, side effects, and permission constraints; only an explicit alternative/edge case would be needed to be fully complete.

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 the schema documents all three params including defaults for name and visibility. The description adds no param syntax or format detail beyond that, so it meets the baseline of 3 rather than adding meaning.

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

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

'Fork an existing dashboard into a new artifact you own, preserving lineage' gives a specific verb, resource, and outcome. It is clearly distinguishable from siblings like save_dashboard, update_dashboard, and search_dashboards.

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?

Explicitly states the intended context ('adapt a popular dashboard rather than build from scratch') and gives a concrete example, plus names update_dashboard as the follow-up for editing the fork. No explicit 'when not to use' or named alternative to forking, so short of a 5.

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

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

Annotations already declare readOnly=false and destructive=false, so the description is not the sole source of the safety profile, and it correctly corroborates a non-destructive write. It adds useful value by disclosing the return value ('Returns the new fork ID') despite no output schema, but says nothing about whether the fork is independent of, or affects, the source template.

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 action and followed by the result. No filler or 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?

For a 3-parameter mutation tool with no output schema, the description covers the action and the return value, and annotations carry the safety profile. However, it omits fork independence from the source template and any overwrite/duplication behavior, which an agent would want before calling.

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 three parameters (id, name, parameterOverrides) are already documented in the schema. The description repeats the 'parameter overrides' concept without adding format, merge semantics, or conflict-resolution details 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 (fork) and resource (protocol template), plus the effect: creating a customized copy with parameter overrides. An agent can distinguish it from list-style siblings like get_protocol_forks, though it never explicitly contrasts with create_protocol or fork_dashboard.

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

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

Usage is only implied by the phrase 'create your own version with parameter overrides' – there is no explicit when-to-use statement, no prerequisites, and no named alternative (e.g. create_protocol vs. fork_protocol). Adequate but leaves routing 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 operation is a non-read-only, non-destructive write. The description adds real context beyond that: approval is handled internally by the gateway (citing audit C-03 as the reason the public approve step was removed), and it names the return value (transaction hash). It does not cover failure modes or funding limits.

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

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

Content is front-loaded with the action, then the critical approval caveat, then the return value. The parenthetical audit reference is informative justification rather than padding, though it is the one element an agent could do without.

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 single-parameter mutation with no output schema, the definition covers the action, the surprising internal-approval behavior, and the return shape, which is enough to call it correctly. Gaps are minor: no note on gas, token allowances, or error conditions.

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 for the single address parameter is 100%, so the baseline is 3. The description lifts this slightly by constraining the acceptable input to an escrow address that was created through the protocol, a non-obvious restriction given that generic escrow siblings exist.

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 (Fund) and resource (protocol-created escrow) plus the execution context (on-chain). The qualifier "protocol-created" separates it from the generic escrow siblings such as protocol_create_escrow and get_escrow, so an agent can identify the right tool without opening a 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?

Gives explicit negative guidance: "do NOT call a separate approve first; fund directly," which prevents a common multi-step mistake. It does not, however, spell out prerequisites such as the need for a prior protocol_create_escrow or token/allowance requirements, so the routing guidance is clear but incomplete.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the description is not carrying the safety burden. It adds the scoping trait 'currently active jobs' and names the telemetry fields returned, but says nothing about pagination, ordering, or whether results are global or scoped to the caller.

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 or redundancy. The scope constraint ('currently active') and the payload contents are both stated in the first clause.

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 what is returned (pipeline phase, telemetry status), but for a listing endpoint it omits result volume, ordering, and whether the list is bounded. Complexity is low and annotations cover safety, so it is adequate rather than complete.

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

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

The tool takes zero parameters and schema description coverage is 100%, so there is nothing for the description to clarify. The rubric's baseline for a zero-parameter tool 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 (List) and resource (currently active jobs) plus the two fields returned (pipeline phase, telemetry status). The word 'active' implicitly distinguishes it from list_jobs and the historical get_telemetry_logs, but it never names a sibling, so differentiation requires the agent's own 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 when-to-use statement and no alternatives named. In a namespace containing get_job_telemetry, get_telemetry_logs, get_telemetry_stats, and system_telemetry, an agent gets no routing signal beyond the adjective 'active'.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so safety needs no repetition. The description adds one genuinely useful behavioral fact — the result carries a trust impact score — but omits return shape, count limits, or pagination for what could be a list result.

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 sentence, front-loaded with the verb and scope, with the trust-score payload appended. Nothing is wasted and there is no preamble.

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 read tool with full schema coverage and safety annotations, the definition covers what to query and hints at the return payload. The only gap is enumeration/pagination behavior, which is minor here and there is no output schema to lean on.

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 single agentId parameter is documented in the schema as 'Agent or kernel ID'. The description's 'a specific agent' adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

Specific verb+resource with a filter scope: 'Get anomalies involving a specific agent' plus a stated payload ('trust impact score'). It is distinguishable from get_unresolved_anomalies by the agent scoping, but it never names that sibling explicitly, so the differentiation is inferred rather than stated.

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 'involving a specific agent' implies when it applies, but there is no explicit when-to-use, no when-not condition, and no pointer to get_unresolved_anomalies or get_anomaly_stats as alternatives. An agent must guess which anomaly tool fits.

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 and destructiveHint=false, so the safety profile is covered. The description adds that results are pre-aggregated rather than row-level, but says nothing about scope (global vs per-agent), time window, or whether counts are cached/live.

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 sentence, front-loaded with the verb and resource, followed by the exact breakdown categories. No filler and nothing repeated from structured fields.

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 enumeration of returned aggregates does useful work. But scope is unresolved: several sibling tools operate per-agent (get_agent_anomalies) or per-state (get_unresolved_anomalies), and this description does not say whether these stats are system-wide or scoped, nor what time range they cover.

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

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

The tool takes zero parameters, so there is no schema surface to compensate for; baseline 4 applies. The description correctly implies no filtering input is required.

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?

Clear verb+resource ('Get aggregate anomaly statistics') and it enumerates the dimensions returned (total, unresolved, by severity, by category), which distinguishes it from list-style siblings. It never names those siblings explicitly, so the differentiation relies on 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?

The word 'aggregate' implies this is for summary counts rather than enumerating individual anomalies, which is a real distinction from get_unresolved_anomalies and get_agent_anomalies. However, there is no explicit when-to-use statement, no exclusion, and no named alternative.

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 and destructiveHint=false, so safety is covered. The description adds nothing beyond that: it does not say what an 'automation status' value represents (e.g., states, last run, errors) or any auth/scope requirement, so it contributes no behavioral context of its own.

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 or redundancy. It is efficiently sized, though the brevity is as much under-specification as economy.

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

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

There is no output schema, so the description must carry the meaning of the returned 'status' — but it never explains what status values or fields to expect. For a query tool with no output schema, the definition is too thin to tell an agent what it will actually receive.

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 ('Source/Destination instrument node ID'), so the schema does the work. The description adds no format, ID syntax, or pairing constraints beyond what the schema states, making the baseline 3 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 ('Get automation status') and scopes it to a single instrument-to-instrument transfer pair, which implicitly distinguishes it from list_automation_status. It stops short of naming that sibling explicitly, so an agent must infer the singular-vs-list 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?

The phrase 'for a specific ... transfer pair' implies a targeted single-pair lookup rather than a bulk listing, which is usable guidance. However, there is no explicit statement of when to prefer this over list_automation_status or what prerequisites (e.g., valid node IDs, existing transfer) apply.

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 and destructiveHint=false, so the safety profile is covered. The description adds that results are ranked by claimed and verified bounties, which is genuine ranking context, but it does not disclose ordering direction, tie-breaking, or whether the leaderboard is global or scoped, leaving the behavior only partially characterized.

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 sentence with the verb, resource, and ranking criterion front-loaded. No filler and nothing to trim.

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, single-optional-parameter tool with no output schema, the description covers what the tool returns and the ranking basis. It does not state the ordering or scope of the leaderboard, which is the only meaningful 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 the single limit parameter is documented in the schema with its default of 10. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (bounty hunter leaderboard) and qualifies the content as top operators ranked by bounties claimed and verified, which distinguishes it from list_bounties, claim_bounty, and verify_bounty. It does not explicitly name the sibling it is differentiated from, 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 description says what the tool returns but gives no when-to-use context, no exclusions, and does not point to alternatives such as get_operator_earnings, get_operator_dashboard, or list_bounties for per-operator or per-bounty data. The agent must infer the usage scenario on its own.

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 carry the safety profile (destructiveHint=false), and the description adds the workflow dependency on calculate_price. However, it never reconciles the 'Get' framing with readOnlyHint=false, and it gives no hints about return shape or whether calling it has side effects beyond fetching.

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 zero filler, and the purpose is front-loaded ahead of the sequencing instruction.

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 three-parameter read tool with no output schema and a nested input object, the description covers purpose and the critical dependency on calculate_price. It is complete enough to invoke correctly, though it leaves the return payload and the readOnly=false behavior undocumented.

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 enumerates the option groups that come back but adds nothing about the `type`, `profileId`, or nested `selections` parameters beyond what the schema already documents.

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 ('Get configuration options for a capability type') and enumerates the option groups returned, so the agent knows what it retrieves. Sibling differentiation is only implicit via the calculate_price link rather than a named contrast.

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

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

Gives explicit sequencing ('Use before calling calculate_price'), which tells the agent where this tool sits in the workflow and why it is needed. It does not state when not to use it or name an alternative, so it falls short of a 5.

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

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

Annotations already declare it a safe read (readOnlyHint=true, destructiveHint=false), so the safety burden is covered. The description adds genuinely useful behavioral context beyond that: the tool returns three specific artifacts and notes the Filecoin deal ID is conditional ('if available'). It discloses no auth or rate-limit behavior, but for a simple getter this is solid.

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 efficient sentence, front-loaded with the verb and resource, with the return payload described immediately after the dash. No wasted words.

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

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

There is no output schema, so the description usefully carries the return-value burden by naming the CIDs and deal ID. Combined with annotations covering safety and a fully documented single parameter, an agent has everything needed to invoke it; only the absence of sibling routing keeps it from a 5.

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 only one parameter (bundleId) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax, format, or scoping detail about the bundle ID. 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?

The description gives a specific verb (Get) and resource (IPFS CIDs for a bundle) and even enumerates the returned artifacts (primary CID, metadata CID, Filecoin deal ID). It is clear on its own, but it does not distinguish itself from the sibling retrieve_ipfs, 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?

There is no statement of when to use this tool versus alternatives such as retrieve_ipfs or get_evidence_bundle. Usage is only implied by the name and resource. No prerequisites or exclusions are given.

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 and destructiveHint=false, so safety is covered. The description adds no behavioral context beyond that: it does not say what happens if no IP registration exists (null, empty, or error), what the return payload contains, or whether the lookup is chain-backed or cached.

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; the target resource and lookup key appear immediately. It is efficient, though extremely terse, leaving no room for the routing or edge-case context an agent would benefit from.

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

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

For a simple annotated read with a complete one-parameter schema and no output schema, the description covers the basics but is silent on the not-found case and on how the result relates to sibling IP tools. Adequate but with a clear gap around error/empty behavior.

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 parameter, so the schema already documents 'capabilityId' fully. The description only restates the key relationship ('by its capability ID') without adding format, source, or constraints — 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?

The description states a specific verb ('Get') and resource (the Story Protocol IP registration for a capability) and specifies the key used ('by its capability ID'). This is unambiguous on its own, though it does not explicitly distinguish itself from nearby siblings like get_registration, get_ip_lineage, or register_capability_ip.

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 alternatives such as get_registration or get_ip_lineage, nor any stated preconditions (e.g., the capability must already have a registration). The agent must infer usage entirely from the name and purpose.

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 a safe read, but the description adds real behavioral context the annotations cannot: a 30-minute proposal TTL and the specific failure codes (404 unknown, 410 expired). The expiry semantics materially change how an agent must sequence calls.

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

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

Three short sentences, front-loaded with what it does, then error semantics, then usage. Every clause carries information; nothing is restated from the schema or annotations.

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 carries the burden of return behavior; it fully covers the error cases but never says what a retrieved composition contains. For a read-by-id tool with known error semantics, this is nearly complete, missing only the payload 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 100%, so the id parameter is already documented as coming from propose_composition; baseline would be 3. The description adds meaning beyond the schema by implying the id is only valid within a 30-minute window, which is a validity constraint on the parameter itself.

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 ('Retrieve a previously-proposed composition by id') and immediately frames the resource as the artifact produced by propose_composition and consumed by execute_composition. An agent can distinguish it from both siblings without opening a 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?

Gives two concrete use cases: inspecting a plan before executing and recovering a plan id after a restart. It stops short of naming the alternative tools (propose_composition / execute_composition) explicitly, so the routing is strongly 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?

Annotations only declare readOnlyHint=true; the description adds genuinely non-obvious traits: zero regeneration cost, an access-control rule (public/unlisted accessible to all, private owner-only), and a hidden side effect ('Increments the load counter'). The side effect is notable because a read-only-hinted call still mutates a counter, but it is disclosed rather than hidden. Failure modes (e.g. private artifact not owned) are not described.

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 action and return value, then usage, then access rules, then side effect. Every sentence carries distinct information with no repetition of the schema.

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

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

An output schema exists, so the description need not enumerate returns beyond the brief 'manifest + metadata' summary. It supplies the usage context, access control, and side effect an agent needs, and the parameter is fully documented in 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 100% and the single parameter already documents the ua_... id form and the slug tail of /a/<slug>. The description's 'by its id or slug' merely restates that, adding no syntax or constraint beyond the schema. 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 ('Recall a saved dashboard by its id or slug') and immediately says what is returned ('full artifact (manifest + metadata)'). It is easily distinguishable from save_dashboard, update_dashboard, search_dashboards, fork_dashboard, and get_operator_dashboard, and the reload-vs-regenerate framing sharpens the intent.

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 concrete when-to-use with a real user utterance ('open my pizza dashboard') and an explicit when-not (don't regenerate). It never names search_dashboards as the alternative for when the id/slug is unknown, which is the obvious complementary case, so it stops just short of full 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds scope ('network-wide') but says nothing about the time window, granularity, or whether the timeline is bounded — notable given the tool accepts no parameters at all.

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 — the verb, scope, and intended application all appear immediately and nothing is repeated.

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 input schema, no output schema, and no annotations beyond read-only safety, the description carries the full burden of explaining what comes back. It names the data ('demand vs supply timeline') but leaves the return shape, time horizon, and granularity unstated, which is a meaningful gap for a parameterless reporting tool.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there are no parameter semantics for the description to clarify or omit.

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 ('Get') and a specific resource ('network-wide demand vs supply timeline data'), which an agent can distinguish from nearby siblings like get_top_demand or submit_demand. It stops short of explicitly contrasting itself with those siblings, so it is clear but not 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?

The phrase 'for capacity planning and market analysis' implies a use context, but there is no explicit when-to-use/when-not guidance and no named alternative for related queries such as get_top_demand or get_depin_stats. Usage is inferred 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered without the description's help. The description contributes the scope of the payload (three stat categories), which is modestly useful context, but says nothing about freshness, aggregation window, or authorization. Adequate but not rich.

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

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

A single tight sentence fragment with no waste and the three content areas front-loaded. It reads as a label rather than a sentence, but nothing extraneous is present.

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 parameterless read-only stats tool with no output schema, the description is just barely sufficient: it hints at the returned subject matter, but an agent gets no sense of shape or scope of the three payloads it will receive. No return-value explanation is possible since no output schema exists, which limits how complete this can be.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description adds no parameter information because none is required.

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 fragment names three concrete data domains (DePIN treasury, soulbound capability certificates, reward epoch stats), which tells an agent roughly what content comes back. But it has no verb and never states that it retrieves or returns anything, so the action is only inferred from the tool name. It is more informative than a tautology yet not a clean verb+resource statement.

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 indication of when to call this versus siblings such as get_token_balance, get_operator_earnings, get_settlement_epochs or get_operator_certs, which plausibly overlap with treasury, certificate and epoch data. No preconditions, no exclusions, no alternatives are offered.

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 and destructiveHint=false, so safety is covered. The description adds useful content about what the snapshot contains (utilization, demand, pricing), but says nothing about return shape, pagination, or freshness of the market data. Adequate but not rich.

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 that names the resource first and the payload second, with 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?

For a zero-param read tool with annotations covering safety and no output schema, the description conveys enough to call it correctly. The only missing piece is any hint about result size or data freshness, which is minor here.

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?

Zero parameters, so there is no schema semantics to compensate for; baseline is 4. The description correctly implies an unfiltered full listing, though it is silent on whether the result set can be scoped.

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 (List) and resource (equipment classes) with concrete examples (FDM printers, CNC mills) and names the data payload (utilization, demand, pricing). An agent knows what it gets, though the description doesn't distinguish this from near-neighbors like marketplace_categories or pcc_capture_class_registry.

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 alternatives named among the many sibling list_/get_ tools. An agent must infer the call context entirely from the name.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: the DB path returns milestones and disputes, while the address path reads live from the blockchain. That data-source distinction is exactly the kind of behavioral context annotations don't convey.

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 core purpose, then the branching input guidance. Nothing wasted and 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?

For a single-parameter read tool with annotations covering safety and no output schema, the description covers input modes and what the DB path returns. It is complete enough to call correctly, though it doesn't mention return shape for the on-chain path or any error behavior for invalid IDs.

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 schema already describes escrowId as 'DB escrow ID or on-chain contract address (0x...)'. The description's dual-mode explanation largely reiterates the schema, adding the parenthetical about milestones/disputes for the DB mode but no new syntax or format detail. 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?

Specific verb+resource ('Get escrow details') that clearly states what the tool does, and it explains the two input modes (DB record vs on-chain). It doesn't explicitly distinguish itself from siblings like get_escrow_chain_state, get_escrow_dispute, and get_escrow_events, so sibling differentiation is implied rather than stated.

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 guidance on how to choose between the two input modes (DB ID vs EVM address), which is a form of usage guidance. However, there is no comparison against alternative escrow-reading siblings, so an agent must infer when this tool is preferred over get_escrow_chain_state or get_escrow_dispute.

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 and destructiveHint=false, so the safety profile is covered. The description adds that it returns the FULL state including all milestones, but says nothing about auth requirements, return shape, or pagination. With annotations carrying the safety burden, 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?

Two tight sentences with zero waste; the "what it does" clause is front-loaded and the comparative routing note follows immediately.

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 single-param, read-only tool with no output schema, the description covers purpose, scope, and sibling routing, which is nearly everything an agent needs. It could mention what the returned milestone data includes, but that gap is 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% for the single address parameter with a clear 0x... description, so the schema does the work. The description adds no format or constraint detail beyond what is already documented, making 3 the correct 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 (Read) plus resource and scope (full on-chain escrow state with all milestone details from the blockchain), and explicitly distinguishes itself from the sibling get_escrow. An agent can tell the two apart 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?

"More detailed than get_escrow for on-chain contracts" gives a clear condition for choosing this over get_escrow, effectively naming the alternative. It stops short of stating when NOT to use it (e.g., off-chain or summary-only needs), so it is strong but not fully explicit.

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 and destructiveHint=false, so safety is covered by structured data. The description adds one piece of context beyond that – the data is read 'from the blockchain', implying an on-chain rather than cached/indexed source – but says nothing about latency, freshness, or what happens for an invalid milestone index.

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; every word (read, dispute state, milestone, blockchain) carries information. Nothing to trim and nothing important deferred.

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 tool whose annotations already cover the safety profile and whose schema fully documents inputs, the description covers the essentials. Output shape is unspecified but no output schema exists, so 'dispute state' is a reasonable, if thin, signal.

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 address and milestoneIndex are already documented with format hints (0x..., 0-based). The phrase 'for a specific milestone' restates the milestoneIndex parameter without adding syntax, bounds, or error behavior, 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 (read), resource (dispute state), and scope (a specific milestone, on-chain). An agent knows what it returns. It does not, however, differentiate itself from close siblings such as get_escrow, get_escrow_chain_state, or get_escrow_events, which is what a 5 would require.

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 and no mention of alternatives, even though the sibling list contains several overlapping escrow/dispute readers (get_escrow, get_escrow_chain_state, get_escrow_events, dispute_verification). The agent must infer the selection criterion from the resource 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=true and destructiveHint=false, so safety is covered. The description adds value by naming the event types returned, but says nothing about pagination, ordering, or how fromBlock scopes the result.

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

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

Two tight sentences, front-loaded with the core action and followed by the return categories. 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?

With no output schema, the description partially compensates by enumerating the returned event types. Combined with full schema coverage and safety annotations, an agent has enough to call it correctly, though return format and range behavior remain 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 100%, so both address and fromBlock are documented in the schema. The description adds no syntax, format, or default details beyond that, 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?

The description states a specific verb and resource ('Get on-chain event history for an escrow contract') and enumerates the event categories returned. It is clearly distinguishable from get_escrow or get_escrow_chain_state, but 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?

There is no guidance on when to use this versus get_escrow, get_escrow_chain_state, or list_escrows. The purpose implies a use case (inspecting events), but no conditions or exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds return-content context (encrypted payload + key capsules), but omits the downstream implication that decryption requires another tool (e.g., lit_decrypt) and whether access grants are 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?

Two tight sentences, action first and return value second, with no filler. Nothing repeats the name gratuitously beyond the necessary verb-resource pairing.

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 single-parameter read with no output schema, the description does the minimum by naming the returned fields. It stops short of explaining what key capsules enable or how this fits the evidence workflow, leaving the agent to infer the decryption step.

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 single bundleId parameter is already documented there; the description only restates 'by its bundle ID' without adding format, origin, or how the ID is obtained. Baseline 3 is appropriate when the schema carries the parameter burden.

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: retrieves an encrypted evidence bundle identified by bundle ID, and describes the return content (encrypted payload plus key capsules). It does not, however, distinguish itself from close siblings such as get_bundle_ipfs, list_evidence, or verify_evidence_zk.

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 rather than the alternatives in a crowded evidence family (get_bundle_ipfs, list_evidence, archive_encrypted_bundle, grant_evidence_access). No prerequisites or preconditions are mentioned.

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 readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description mentions 'step progress and status' as what is listed, which adds some context about return content, but it does not describe pagination, ordering, or other behavioral traits. With annotations covering safety, 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?

The description is a single, efficient sentence that is front-loaded with the main action. It earns its place without waste, though it could be slightly more informative.

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 list tool with one well-documented parameter and no output schema, the description is minimally adequate. It does not explain what 'step progress' entails or the structure of returned orders, which might be helpful. However, given the annotations and schema, it is sufficient to call correctly but leaves gaps in understanding the output.

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%, with the single parameter 'status' fully documented including enum-like values in the schema description. The tool description does not add any parameter details beyond what the schema provides. Baseline 3 is correct when schema does the heavy lifting.

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

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

The description states a specific verb+resource: 'List equipment installation orders with step progress and status.' This is clear about what the tool does. However, it does not distinguish itself from other list/get tools in the sibling set, such as get_shipments or get_equipment_classes, beyond the resource name itself.

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 guidance on when to use this tool versus alternatives, nor any conditions or exclusions. The description merely states what it does; it does not help the agent decide between this and similar listing tools like get_shipments or list_jobs.

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 and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that the result is a lineage chain spanning parents and derivative job registrations, but says nothing about depth limits, pagination, or behavior when the IP has no derivations.

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

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

A single tight sentence with the verb front-loaded and no filler. The em-dash clause is informative rather than redundant, though 'derivative job registrations' could be marginally clearer.

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

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

For a simple, single-parameter read tool with no output schema, the description gives enough to know what the call returns conceptually. Missing only edge-case behavior (empty lineage, depth) that an agent might want before relying 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?

With one parameter at 100% schema description coverage ('IP asset ID'), the schema carries the semantics. The description only restates that the lookup is 'for an asset' and adds no format, ID-prefix, or validation detail beyond that.

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 ('Get the full IP lineage chain') and enumerates the chain's components (parent capabilities and derivative job registrations), which distinguishes it from the many other `get_*` IP tools. It does not explicitly name a sibling to contrast with, 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?

There is no guidance on when to prefer this over adjacent tools like get_capability_ip or get_registration, nor any prerequisite or exclusion stated. The agent must infer the use case from the description 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=true and destructiveHint=false, so the safety profile is covered. The description reinforces this by describing a snapshot/read and names the fields returned, which is useful but not rich behavioral context (no auth, freshness, or pagination notes).

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 em-dash clause that front-loads the core action and then lists the payload. No filler, though it is brief to the point of omitting routing guidance.

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 names the returned figures, and annotations cover the read-only nature. For a one-parameter read tool this is nearly complete, missing only a pointer to the related claim tool.

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

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

Schema description coverage is 100% with a single required ipId parameter, so the schema already documents the only input. The description adds no format or identifier guidance beyond the schema, making 3 the appropriate 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 (get) and resource (revenue snapshot for an IP asset) and enumerates the returned figures (total earned, pending claims, recent payments). It is distinguishable from the similarly named claim_ip_revenue, though it never names that sibling 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 or when-not-to-use guidance is given. With a sibling named claim_ip_revenue in the toolset, the agent gets no help deciding between reading revenue and claiming it.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds only the content categories returned; it says nothing about authorization requirements, whether a missing job errors or returns empty, or pagination. Reasonable but thin given annotations carry the main load.

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

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

A single front-loaded sentence with no filler, and the returned-content list is placed immediately after the verb+resource. It is efficient, though slightly terse for a tool with this many siblings.

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 simple read tool with one required parameter, full schema coverage, and annotations covering the safety profile. Since no output schema exists, the enumeration of returned content (progress, evidence bundles, milestones) does useful work, though the missing sibling differentiation is a residual 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 there is a single required parameter, so the schema already documents jobId fully. The description adds no format or sourcing detail beyond what the schema provides, which matches the baseline 3 for schema-documented parameters.

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 ('Get') and resource ('job') and enumerates the payload (progress, evidence bundles, milestones), which is more than a tautology. It does not, however, differentiate itself from close siblings such as get_job_telemetry, get_kernel_jobs, or list_jobs, leaving the agent to infer the boundary.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no named alternative. With siblings like get_job_telemetry and list_jobs in the same namespace, the description should say when to prefer this tool over them but offers nothing.

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 and destructiveHint=false, so safety is covered. The description adds genuine value by describing the returned content (all phase transitions with timings and metadata), but it omits scope limits such as pagination, retention window, or whether the timeline is complete for finished jobs.

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 sentence, front-loaded with the verb and resource, and the em-dash clause adds the payload detail without padding. 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 one-param read tool with annotations covering safety and no output schema, the description conveys the return shape adequately. What is missing is differentiation from the many sibling telemetry/job tools, which an agent needs in order to pick 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?

There is a single required param, and schema coverage is 100% ('Job ID to get pipeline timeline for'). The description's 'for a specific job' merely restates 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?

The description names a specific verb and resource ('Get full event timeline for a specific job') and even enumerates the payload's nature ('phase transitions with timings and metadata'). It is clear, but it never distinguishes itself from close siblings such as get_job, get_telemetry_logs, get_active_telemetry, or get_telemetry_stats, leaving the agent to guess which timeline/telemetry tool 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 statement of when to use this tool versus alternatives, no prerequisite (e.g. job must exist or be in a terminal state), and no exclusion. With five-plus telemetry- and job-related siblings, the absence of routing guidance is a real gap.

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 this as a safe read (readOnlyHint=true, destructiveHint=false), so the description's main job is disclosing what comes back. It does so by naming the richer contents (full capability objects, devices, queue), which is meaningful since there is no output schema. It stops short of describing pagination, missing-kernel behavior, or payload size.

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 filler. The contents list is placed immediately after the verb-resource pair, so the most useful information is read first.

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

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

For a simple single-parameter read with no output schema, naming the returned sections compensates well for the absent return-value documentation. It is only mildly incomplete in not covering edge cases such as an unknown kernel ID or how this relates to the similarly-named kernel sub-resource getters.

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?

Only one parameter, kernelId, and schema description coverage is 100%, so the schema already documents it. The description adds no format hints (e.g., where a kernel ID comes from) beyond what the schema provides, matching the baseline of 3.

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 (get) and resource (kernel) and enumerates what the payload contains: capability objects, devices, and queue. This partially differentiates it from siblings like get_kernel_devices, get_kernel_jobs, and get_kernel_sensors, though it does not explicitly say it supersedes them.

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

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

Usage is only implied: fetch the full detail record for one kernel by ID. There is no explicit guidance on when to prefer this over list_kernels or the narrower get_kernel_devices / get_kernel_sensors calls, and no exclusions or prerequisites given.

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 and destructiveHint=false, so the safety profile is clear. The description adds useful content context about what the list includes, but does not disclose other behavioral traits like authentication requirements, pagination, or rate limits.

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

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

The description is a single, front-loaded sentence with no wasted words. It conveys the core purpose and extra content efficiently.

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

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

For a simple read-only list tool with annotations covering safety, the description is mostly complete: it states the resource and what is included. It does not mention return structure or pagination, but no output schema exists and the tool is straightforward.

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 kernelId parameter, so the schema already documents it. The description mentions 'a specific kernel' but adds no new syntactic or semantic detail beyond what the schema provides, making the baseline of 3 appropriate.

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

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

The description states a specific verb ('List') and resource ('all devices registered under a specific kernel'), including what extra data is returned ('adapter configs and device types'). It does not explicitly differentiate from siblings like get_kernel_jobs or get_kernel_sensors, so it falls 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 guidance on when to use this tool versus alternatives such as get_kernel_sensors or get_kernel_jobs. It only describes the output, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that returned jobs include status and progress, but says nothing about pagination, ordering, auth, or result limits.

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

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

A single front-loaded sentence with no redundant clauses. It is appropriately sized, though it could have used a second short sentence for routing without becoming bloated.

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, read-only list tool with no output schema, the description covers the core action and return content (status/progress). Pagination and ordering are unaddressed, but the simple schema and annotations carry most of the remaining burden.

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 there is one required kernelId documented as 'Kernel ID'. The description adds no parameter syntax or constraints beyond what the schema already provides, making 3 the 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 (List) and resource (jobs submitted to a specific kernel), which distinguishes it from broad list_jobs and single-job get_job. It does not explicitly name siblings, so differentiation is only implicit.

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

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

Gives no explicit when-to-use guidance, prerequisites, or alternatives. The agent can infer it is for kernel-scoped job listing, but nothing steers it between this, list_jobs, get_job, or get_job_telemetry.

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 and destructiveHint=false, so the safety profile is covered. The description adds that it returns 'live channel descriptors', but does not describe pagination, auth needs, freshness semantics, or what 'live' operationally means.

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 waste: the core operation is front-loaded, and the return-type note adds useful information without 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 simple read-only lookup, the description covers purpose and a basic return type. However, with no output schema, it leaves the actual shape and meaning of 'live channel descriptors' vague, which is a gap for an agent consuming 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 the single kernelId parameter is already fully documented. The description's 'for a specific kernel' repeats the schema rather than adding syntax, format, or constraint detail.

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 ('Get sensor channels') and scopes it to 'a specific kernel', which helps distinguish it from broader sensor or kernel tools. It does not explicitly name an alternative sibling, so it stops short of the highest clarity band.

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

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

The description gives no when-to-use guidance, prerequisites, or alternative tools. It only implies usage from the required kernelId and the phrase 'for a specific kernel'.

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 and destructiveHint=false, so safety is covered. The description adds that the tool returns conditions gating decryption, but says nothing about permissions required, pagination, or error behavior for non-Lit-encrypted bundles.

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