Rightshold

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

Adds substantive behavior beyond annotations: it discloses what is returned (matched license/resource, the understood use, and a deterministic answer with reasons), that it asks for clarification rather than guessing, and that it is free with no key. The clarification behavior and the 'verify the understood use' caveat are the kind of context annotations cannot express. It does not address the readOnlyHint=false side effect (persisting the assessment when a key is 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?

Front-loads the call condition, then the return shape, then the caution and cost note. Four sentences, each doing work, though the middle sentence packs several ideas together.

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

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

An output schema exists, so return values need not be detailed, yet the description still summarizes them helpfully. Combined with annotations covering safety and a well-documented nested schema, an agent has enough to call correctly; only the routing versus similar siblings remains implicit.

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 75%, with rich inline docs for intended_use flags and resource_id, so the schema carries the burden. The description only alludes to these inputs indirectly ('the license or registered resource', 'the use it understood') without adding format or semantic detail. 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 capability: answering rights/licensing questions phrased in plain English, with a concrete example ('Can I use CC BY-NC 4.0 images in a paid ad campaign?'). The 'plain English' framing implicitly distinguishes it from structured siblings like check_license and assess_resource_for_use, 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?

Gives a clear trigger condition ('Call when you have a rights or licensing question in plain English') plus a worked example, and adds a post-call caution ('Check the understood use before relying on it'). It does not name alternatives or state exclusions, so the agent must infer that structured checks belong to the sibling tools.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so safety is largely covered. The description adds genuine context beyond them — deterministic behavior, version-binding, four dispositions with reason codes, and the explicit absence of a trust score — but it never explains why a pure assessment is not read-only (the schema's deprecated api_key field is the only place that hints the assessment is persisted to your account).

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

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

Two dense sentences with no filler, and the core capability plus the output contract are front-loaded. The style is compressed to the point of being slightly cryptic, but every clause 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?

An output schema exists, so return values need not be described, and the description does cover determinism, version-binding, and the four-disposition contract. The remaining gap is behavioral: an agent cannot tell from the description what side effects justify readOnlyHint=false or what happens when a right is not documented — gaps that matter for a gating decision 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 67% and the nested intended_use object is itself well documented, so the schema does most of the work. The description reinforces that the intended-use flags are rights the check must find documented and that the result is bound to a specific resource version, which adds a little meaning, but it gives no syntax, default, or geography/duration guidance 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?

It states a specific verb and resource — a deterministic rights assessment of a resource against an intended use — and pins the scope to the exact resource version, license, and publisher authority. It differentiates itself from score-based siblings by declaring 'exactly four dispositions with reason codes; no trust score', but it never names the closest relatives (check_license, gate_check, check_rights_batch), so an agent must infer the boundary.

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

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

There is no when-to-use guidance at all: no statement of when this should be preferred over check_license, gate_check, kya_check, or check_rights_batch, and no prerequisites such as having resolved a resource version or obtained a rights key. The binding language ('bound to the exact resource version') hints at a precondition but never states it as a rule.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real context beyond them: 'Free, no key' discloses auth/cost expectations, and it previews that the response includes duties covered plus what is still missing.

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 trigger, then the deliverable, then a compact example call. Three short sentences with no filler, though the embedded JSON example makes the final sentence dense.

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

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

An output schema exists, so return-value enumeration is not required, yet the description still hints at the response shape. With trigger, auth note, and a full parameter example provided, the only unmet need is how to format the sole required 'license' field, which the example partly resolves.

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

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

Schema coverage is 0%, so the description must carry the load, and the worked example call supplies values for all five parameters including the optional title, author, source_url and changes. It does not explain the string-vs-boolean duality of 'changes' or the expected license identifier format, leaving a small gap.

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

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

States a specific verb and deliverable: it produces the attribution line a license requires, in three formats. This is clearly distinguishable from siblings like check_license or license_compatibility, and the trigger condition ('reuse material that requires credit') pins down the 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?

'Call when you reuse material that requires credit' gives an explicit usage trigger. It does not name an alternative sibling or state when NOT to use it (e.g. versus check_license or issue_rights_manifest), so it stops 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?

Goes well beyond the readOnly/idempotent/non-destructive annotations: it discloses that the service is free and needs no key, that curated readings exist for common ids while others return needs_review, the full verdict vocabulary plus duties and an uncertainty block, and the platform allow-list for source_url. The annotations cover safety; the description covers coverage limits, cost/auth, and answer shape.

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

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

Front-loads the imperative call-to-action and the what-it-checks clause before the return-value detail, so the critical routing information comes first. It is a dense single block and the trailing example duplicates schema guidance, but nearly every clause carries load.

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

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

For a tool with a nested object parameter, two mutually exclusive input paths, and an output schema, the description supplies the missing behavioral context: coverage boundaries, auth/cost, verdict set, and the uncertainty block. Nothing an agent needs to invoke it correctly 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: license vs source_url are presented as alternatives, the curated-vs-needs_review behavior of arbitrary SPDX ids is explained, and a concrete worked invocation shows the intended_use nesting. Little more could be added beyond field-level semantics already in the schema.

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

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

States a specific verb (check) and resource (a license), and specifies both input modes: a raw SPDX id, or the license declared by a page on a named set of hosts. The scope note 'one license' implicitly separates it from batch siblings like check_rights_batch and from license_compatibility or assess_resource_for_use.

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?

Opens with an explicit trigger: 'Call before using any image, text, dataset, code, font or model you did not create,' which is exactly the context an agent needs. It does not, however, name a sibling alternative or state when to prefer a different tool (e.g., batch or multi-license checks), so routing above the single-license case is 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds real behavioral value beyond them: the source is a signed revocation list, and it disambiguates that 'unknown' means unvetted rather than unsafe — a distinction that changes how an agent acts on 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?

The pre-install purpose and result categories are front-loaded in one dense sentence, followed by a compact call example. No filler; every clause either scopes the check or disambiguates an outcome.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain return values — yet it usefully sketches the outcome categories. The only meaningful gap is the missing guidance on how the three alternative identifier inputs relate to one another.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: it clarifies that the hash is SHA-256, the url may be an endpoint or package URL, and the slug is a store slug, plus a concrete invocation example. It omits whether exactly one of the three optional inputs is required and how conflicts between them are resolved.

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 ('pre-install check against the Rightshold Store and its signed revocation list') and enumerates the exact answer space: on record, vetting tier, rating record, REVOKED, or unknown. An agent can distinguish this from siblings like search_store or registry_lookup without opening either schema.

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

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

The 'pre-install' framing establishes clear when-to-use context, and the REVOKED/unknown interpretation tells the agent what to do with the result ('do not install'). It does not name an alternative tool or state exclusions, so it stops 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?

The description discloses useful operational context the annotations do not: cost ('Free, no key'), auth posture, and the reuse of licenses already held on the account. Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false), so this is adequate rather than rich; no rate-limit or storage detail is given.

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

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

Four tight sentences, front-loaded with the trigger ('Call before shipping'), then behavior, then output states, then an example. No filler, though the example sentence is somewhat long.

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 batch tool with an output schema already documenting return values, the description covers purpose, trigger, input options, and outcome states. Prerequisites beyond 'no key' and limits other than the 100-item cap are the only notable omissions.

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 only 67% schema coverage and bare string params in the schema, the description compensates by explaining that each item can be an SPDX id, registered resource_id, or asset URL/name, and provides a concrete example call. This meaningfully reduces ambiguity about how to fill 'items'.

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: 'Checks up to 100 items ... for their intended uses', with the accepted input kinds enumerated. It clearly reads as a batch counterpart to single-item checks like assess_resource_for_use, though it does not name 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?

'Call before shipping anything that bundles third-party assets' gives a clear trigger context. It stops short of naming when-not-to-use or which sibling to prefer for single items.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world). The description adds genuinely new context: the call is free, it is a deterministic policy evaluation over a fixed list of policy flags, and it returns allow/deny with reasons rather than a bare boolean. It does not disclose auth requirements, rate limits, or what happens when optional inputs are omitted.

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 'Free.' followed by the substantive content in a single dense sentence; the long parenthetical policy list is the only bloat, but it does carry real information. No filler or restatement of the title.

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

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

An output schema exists, so return values need not be explained. Still, for an 8-parameter tool with zero required params and nested policy/receipt/request objects, the description gives no guidance on which inputs are needed for which policy configuration, leaving a real gap for an agent assembling a call.

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

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

Schema description coverage is only 13% (one of eight params documented), so the description must compensate. It does map most artifacts to concepts – RS-KYA token, handle, Web Bot Auth signature, Rights Receipt, clearance, intent token – and enumerates the policy sub-fields, but asset_sha256 is never mentioned and the distinction between 'agent' handle and 'kya_token' is left unclear.

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 action (checking KYA token, Web Bot Auth signature, Rights Receipt, clearance and intent token against a site policy) and a specific output (allow/deny with reasons). It is clearly an authorization-decision tool rather than a token verifier, which distinguishes it in spirit from kya_check/kya_verify, but it never names those siblings or explicitly contrasts itself 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?

Usage is implied by the title ('may a site accept this agent or upload?') and by the enumerated policy fields, so an agent can infer this is the combined gate decision. However there is no explicit when-to-use guidance, no statement of when to prefer kya_check or check_license instead, and no 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 already cover readOnly/idempotent/safety. The description adds meaningful context beyond them: no account or key required, and the policy statement that nothing buys placement, grade, KYA level, verdict, or review. Return shape is left to the 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?

Single front-loaded sentence that leads with the use case. The long em-dash clause enumerates contents compactly, though the trailing policy clause makes it slightly dense.

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

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

For a zero-param read tool with annotations and an output schema, this covers when to use it, that no auth is needed, and the semantic guarantees of the pricing data. Nothing an agent needs 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?

Zero parameters, so baseline is 4 by rule. The description correctly indicates a no-input retrieval call ('No account or key needed'), consistent with the empty 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+resource ('see what Rightshold costs') and enumerates the concrete contents of the pricing data returned. Clearly distinguishable from siblings like check_listing or search_marketplace.

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 frames the when: 'before you sign up or plan spend', which distinguishes it from sign_up. No exclusions or alternative-routing guidance are given, but the use context is clear.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds two things they cannot: the data is self-reported (a trust caveat that affects how an agent should weight the result) and no credentials are required. It stops short of noting caching, freshness, 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?

Front-loaded with the decision rule and scoped well, but the long comma-separated inventory of components is dense and partially duplicates the output schema. Two short sentences then cleanly deliver the caveat and the alternative.

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-parameter, read-only status tool with an output schema and full annotations, the description covers the remaining burden: when to call it, that the data is self-reported, that no auth is needed, and where to get an independent verification. Nothing an agent needs to invoke 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing the description could add. The enumeration of components is about the response, not about inputs, so it does not raise this score.

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

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

Names a specific verb and resource ('check whether Rightshold is operational') and enumerates exactly what the record contains (component checks, ledger/registry counts, 90-day uptime, incident history). It is clearly separable from siblings like check_conformance, which it explicitly positions as the independent alternative.

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

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

States the trigger condition ('before you depend on it') and a second use case ('to cite its record'), then names the alternative (check_conformance) with the reason to prefer it. Auth precondition is also stated ('no account or key needed').

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real behavioral context beyond them: it commits the result to a ledger (an irreversible side effect), reuses licenses already held, and returns both a signed manifest and a plain-text summary. It omits auth requirements and what happens if some items fail the check.

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 'Use when...' trigger is front-loaded and every clause carries information; the embedded JSON call is compact and illustrates the nested items array. It is a single dense run-on sentence, which is slightly harder to parse than a split structure would be, but nothing is 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 7-parameter tool with nested objects and an output schema, the description covers the core flow, the side effects, and the follow-up tool adequately; return values need not be described since an output schema exists. Remaining gaps are secondary details like auth handling, per-item failure behavior, and the deliverable/items relationship.

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

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

Schema description coverage is only 43%, so the description must compensate, and it does partially by naming resource_id/license/asset as the item inputs and giving a concrete call example that shows the shape of items and intended_use. However, the roles of 'deliverable', 'client', and the relationship between deliverable and items are still unexplained in both description and 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 and artifact ('issue a rights manifest'), names the scope ('a whole deliverable'), and enumerates the core action (checks every third-party input for its use, reuses held licenses). It also names the sibling that inspects the result, verify_rights_manifest, so an agent can distinguish it from check_rights_batch and issue_rights_receipt 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?

'Use when your principal wants signed proof for a whole deliverable' gives an explicit triggering condition, and naming verify_rights_manifest as the checker routes the agent to the follow-up tool. It stops short of explicitly contrasting with issue_rights_receipt (single-item) or check_rights_batch, so the boundary is only implied by 'whole deliverable'.

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 state readOnly=false, idempotent=false, destructive=false, openWorld=false. The description adds substantive behavior beyond that: the receipt is cryptographically signed (keys at /.well-known/jwks.json), committed to the ledger, conforms to rights-receipt/1, and must be shipped as <file>.rights.json. It does not mention ttl/expiry semantics or the idempotency_key retry behavior, which would be valuable for a write 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?

The trigger clause is front-loaded and the supporting detail (standard, signing, filename, example payload) follows compactly. The inline JSON example is dense but directly actionable, and there is little filler prose for a definition of this complexity.

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

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

An output schema exists, so return values need not be explained, and the description does cover the produced artifact and its delivery path. But for a 9-parameter tool with nested objects and only 22% schema coverage, several parameters (ttl_days, resource_id, attribution, agent) go unexplained, which is a real gap despite the otherwise rich framing.

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

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

Schema description coverage is only 22%, so the description must compensate, and it partially does: the worked example pins down the sha256 format (64-hex of the file), the license string, intended_use shape, and asset.kind/name. It says nothing about ttl_days, resource_id, attribution, or agent, leaving several meaningful parameters unelaborated in both schema and description.

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

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

The description states a precise verb+resource ('Issue a Rights Receipt') and defines the artifact concretely: a signed proof binding a file's SHA-256 to its license, intended use, verdict and duties. However, it never distinguishes this tool from the very similarly named sibling issue_rights_manifest, which an agent must disambiguate before choosing.

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

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

It gives a clear conditional trigger: 'Use when your principal wants signed proof that one asset you ship was cleared.' That is real when-to-use guidance, but there is no when-not guidance and no reference to the closest alternative (issue_rights_manifest), so the routing decision is left 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: evaluation happens against the live record, require_active defaults to true, and the response carries reasons for denial. Return-format detail is partly redundant against the output schema, keeping this from a 5.

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

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

Two sentences plus an example, all front-loaded and free of filler; the action and return are stated before the parameter list. The field enumeration is dense but each item earns its place since the schema itself is undocumented.

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 with an output schema and rich annotations, the description covers the action, all policy knobs, defaults, and the allow/deny outcome. The only real omission is routing guidance relative to the sibling KYA tools, which keeps it short of perfect.

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

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

Schema coverage is 0%, so the description must carry the burden and it does: it names every policy subfield (min_level, require_active, min_grade, max_open_complaints, require_classes, require_domain, min_tenure_days), states the default for require_active, and supplies a concrete call showing the agent identifier format and sample policy values.

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 uses a specific verb phrase ('Allow or deny an agent against a relying-party policy') and enumerates the policy dimensions evaluated, so the resource and action are unmistakable. It does not, however, contrast itself with the nearby kya_lookup and kya_verify siblings, leaving the agent to infer which of the three to reach for.

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 'evaluated on the live record' framing and made concrete by the inline example call, which shows a realistic invocation. There is no explicit statement of when to choose this over kya_lookup/kya_verify or of any prerequisites, so guidance stops at implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description adds real context: the level taxonomy, the exact facts returned, what is missing for the next level, and the side behavior that credential=true also mints a signed credential and a one-hour kya+jwt token. The only shortfall is that it doesn't note any auth or rate requirements for obtaining a signed credential.

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 primary outcome (the RS-KYA level) followed by the return detail, the optional credential behavior, and a call example. All content earns its place, though the opening sentence is dense enough that it would benefit from being split.

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

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

An output schema exists, so return values need not be spelled out, yet the description still summarizes them usefully, and annotations carry the safety profile. The one substantive gap is that it never positions itself against the sibling kya_check/kya_verify tools, which is the most likely source of mis-selection.

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 50%: 'agent' is documented in the schema but 'credential' has no schema description at all. The description compensates directly by explaining what credential=true returns, and the embedded call example clarifies the required agent format beyond the schema's type/title. This is meaningfully more than the schema 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?

The description states a clear verb (look up) and resource (an agent's RS-KYA level) and even enumerates the returned facts and the L0/L1/L2 level taxonomy. It does not, however, distinguish this from the sibling tools kya_check and kya_verify, so an agent cannot tell from the text alone why it would pick kya_lookup over those.

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 the closely related siblings kya_check and kya_verify, which is exactly where routing guidance is needed. The only contextual hint is that the token from credential=true is 'to present to other services', which implies a use case but not a selection rule between tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description earns credit for a genuinely non-obvious behavior: verification is against the agent's *live* level and status, and validity is revoked when the level drops, the key rotates, or the registration lapses — a stale cached pass is not sufficient. It omits any auth requirements or failure/error semantics, so not a 5.

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

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

A single front-loaded sentence that leads with what is verified and follows with the invalidation semantics; no filler. The parenthetical is dense but every clause carries information, though the run-on structure makes it slightly harder to scan.

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

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

For a 3-optional-param verification tool with an output schema, the description need not explain return values, and it covers the essential behavioral nuance (live-state dependence). The remaining gap is input selection — which of token/signature/credential to supply — which is not addressed anywhere given 0% schema coverage.

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

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

Schema description coverage is 0% across three undocumented parameters, so the description must compensate. It partially does: naming 'a kya+jwt token' versus 'a signed ...Credential' loosely maps to the token/signature pair versus the credential object, but it never states which parameters go together or whether any are mutually exclusive — and all three are optional.

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

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

States a specific verb (verify) and the two concrete resources it accepts (a kya+jwt token or a signed RightsholdKYACredential), plus what is checked: issuer signature, expiry, live level and status. An agent knows exactly what the tool does. It does not explicitly differentiate itself from the near-siblings kya_check, kya_lookup, or ledger_verify, which keeps it at 4.

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 purpose (use to validate a credential before relying on it), and the invalidation clause hints at why you would re-verify rather than cache a pass. However, no when-to-use or when-not-to-use guidance is given relative to kya_check/kya_lookup/check_license, and there are 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 already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds the exhaustive scope of the recomputation, which is meaningful context, but says nothing about cost/runtime for a whole-ledger pass or what a failed verification yields.

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 enumerating exactly what is verified, with no filler or repetition of the title. Every word 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?

With a rich annotation set and an output schema, the description needn't explain return values, and it correctly conveys scope. However, it omits any usage context — when this exhaustive check is warranted and whether it is expensive or replaces narrower checks — leaving a gap for an agent choosing among verification siblings.

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; baseline 4 applies. Schema coverage is 100% and no input semantics are missing.

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 ('Recompute every ...') and enumerates the artifacts verified (payload hash, leaf hash, Merkle root, block hash, chain link, signature), which makes the tool's job unambiguous. It does not explicitly differentiate from sibling verification tools like kya_verify or verify_rights_manifest, but those clearly target other domains.

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 run a full-ledger verification versus a targeted check, no mention of prerequisites, and no named alternative. The only usage signal is implied by the tool name and title.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: that it is free with no key required, and that results classify each pair and name combined duties and the governing license.

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

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

Three sentences: the invocation trigger first, then the returned classification, then a literal example. Every clause carries information (constraints, defaults, sample payload) with 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 nested-input tool with an output schema, the description supplies the missing pieces an agent needs: when to call, the id count bounds, the default intended_use, and a concrete payload. Return values need not be explained further because an output schema exists.

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

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

Schema coverage is 50%, and the schema itself documents intended_use flag semantics, geography and duration_days, but leaves 'licenses' undocumented. The description compensates by stating the 2-25 SPDX id range, the default use case ('default redistribution'), and a full example call including intended_use.

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 ('Checks 2-25 SPDX ids' for combining licenses) plus the outcome vocabulary (compatible / needs_review / incompatible). This distinguishes it from siblings like check_license and assess_resource_for_use, which are not about cross-license combination.

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

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

Gives a clear trigger ('Call before shipping one product that bundles code, data, fonts or media under different licenses') and implicitly scopes usage to multi-license bundles. It does not name or exclude any sibling tool, so the agent must infer why this differs from check_license.

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

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

Annotations already declare readOnly/idempotent/non-destructive semantics, so the bar is lower. The description adds genuine operational context beyond the annotations: the /mcp?toolset=<name>[,<name>] or toolset=all connection pattern and the client-side limitation that only enumerated tools are visible.

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

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

Three tight sentences that front-load the purpose before the connection mechanics and the rationale. Every sentence contributes, though the middle connection sentence is slightly tangential to invoking the tool itself.

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

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

With an output schema present, return values need not be described, and with zero parameters the description carries little structural burden. It supplies enough context for an agent to know this is a discovery step and how to act on 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?

The tool takes zero parameters, so the baseline is 4. The schema is empty and fully covered; the URL toolset syntax referenced is not a tool parameter, so no additional parameter meaning 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 description states the resource being listed ('the toolsets this server offers and the tools in each'), which is clear and specific. It does not explicitly differentiate itself from siblings like start_here, but its discovery/meta role is distinguishable from the rights and license tools.

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

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

It gives clear context for when to reach for this tool: because clients only expose the tools they initially listed, the agent should connect with the toolset its task needs. No explicit exclusions against siblings are offered, which keeps it at a 4 rather than a 5.

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

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

Annotations already cover read-only/idempotent/open-world/non-destructive, yet the description adds real operational detail beyond them: free, no API key required, 6-hour cache, and the important interpretive caveat 'Signals, not a license.' That caveat is exactly the kind of behavioral context annotations cannot 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?

Front-loaded with the trigger ('Call before...'), followed by sources, cost/caching, and a caveat. Dense and useful, though the enumerations of crawler names and sources add length that could be trimmed without much 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?

An output schema exists, so return values need not be described. Combined with the covered sources, caching behavior, and the 'signals, not a license' framing, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description only echoes this with an example call using domain; the optional path parameter gets no added meaning. 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 (reads) and precise resources (robots.txt for 14 named AI crawlers, ai.txt, W3C TDMRep) and the outcome (summarizes whether AI training is opted out). This clearly distinguishes it from license-oriented siblings like check_license or assess_resource_for_use.

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 an explicit trigger condition: 'Call before crawling, quoting or training on content from a website.' It does not name a specific alternative sibling or state when-not to use it, so it stops short of the top tier, but the actionable context is clear.

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 establish read-only, idempotent, non-destructive behavior, and the description adds useful context that the service is free and requires no key. It does not discuss rate limits or error behavior, but it enriches the safety and access profile beyond the structured 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?

The description is front-loaded with the trigger condition, then the lookup format and return fields, then an example call. Every sentence adds distinct value and there is 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 simple two-parameter lookup with an output schema, the description covers when to use it, what it accepts, what it returns, and the optional history flag. It is complete enough for an agent to invoke correctly without needing to inspect 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 0%, so the description carries the full burden and does so well: query accepts a registration number in RS-XXXX-XXXX format or a handle, and history optionally returns the full history report. The example call makes both parameters concrete.

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 precise verb and resource: looking up an agent registration by number or handle, and enumerates the returned fields. It is very clear what the tool does, but it does not explicitly differentiate itself from nearby siblings such as kya_lookup or check_license.

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

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

It gives a clear usage context: call before trusting, paying, or hiring an agent you have not worked with. It does not name alternative tools or state when not to use this one, so it stops 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 read-only, idempotent, closed-world behavior, so the safety profile is covered. The description adds genuine value beyond them by disclosing the returned fields (vetting tier, publisher KYA level, declared permissions, rating aggregate) and the provenance rule that ratings come only from KYA-verified agents.

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

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

Three sentences, front-loaded with what is listed, then filter semantics, then an example call. Efficient overall, though the trailing example-call sentence is a slightly awkward artifact.

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

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

An output schema exists, so return values need not be enumerated for correctness; the description still helpfully previews them. Safety is covered by annotations and filter semantics by the description. Missing only pagination/limit behavior and sibling disambiguation.

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

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

Schema description coverage is 0%, so the description carries the burden and does so: it explains the 'type' enum values (app or skill) and defines 'query' as plain text matched against names and summaries. Only the 200-character cap from the schema is left unaddressed.

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

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

States a specific verb and resource ('List published apps and skills in the Rightshold Store') and enumerates the returned fields. It does not distinguish itself from the similarly named sibling search_marketplace, so an agent must still infer which listing surface to use.

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: 'Filter with type (app or skill) and a plain-text query' tells how to narrow results, and 'Call with {"type": "skill"}' gives a concrete example. There is no when-to-use/when-not guidance and no mention of alternatives such as search_marketplace or check_listing.

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?

Adds substantial context beyond the annotations: the API key is shown only once, accept_terms:true is a legal agreement at /terms, the agent block is transactional ('if that block is invalid nothing is created'), sandbox:true yields an isolated rs_test_ key, and calls are recorded for due-diligence reports. This is rich disclosure of side effects, atomicity and data retention for a non-idempotent 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?

Single dense paragraph, front-loaded with the usage trigger followed by behaviors and parameter notes. Every clause carries information; it is wordy but not 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 6-param creation tool with nested objects and an output schema, the description covers the trigger, the key footprint (shown once, connector settings in the result), sandbox behavior and consent semantics. An agent has enough to call it correctly without further docs.

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 50%, and the description compensates by explaining accept_terms (terms consent), the agent block's purpose and transactional behavior, sandbox isolation, and email optionality. It leaves kind's enum values and display_name unaddressed, but most parameters gain 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?

Specific verb+resource: creates a Rightshold account plus a free API key in one call, with email optional. Clearly distinguishes itself from sibling read/verify tools like kya_check or check_license.

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?

Opens with an explicit trigger: 'Use when your principal wants a Rightshold account.' Gives the key situational detail (one call, email optional). It does not name or exclude alternative siblings (e.g. start_here, kya_check), so it falls short of a full when/when-not statement.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is covered. The description adds genuinely useful context beyond that: 'Free, no key' (auth requirement) and what the zero-argument call returns, which the annotations do not 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?

Front-loaded with the 'call first' directive, and every sentence carries information. The inline JSON examples are slightly verbose but earn their place by showing real invocation shapes.

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

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

An output schema exists, so return values need not be detailed, yet the description still summarizes what comes back (five jobs as calls, connection info). Combined with annotations and full schema coverage, the agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by demonstrating how the optional parameters combine in practice (license+use, or question), clarifying intended usage patterns beyond the schema's field-level docs.

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 function: returning the five jobs Rightshold does as ready calls plus connection info, and optionally answering a license question in the same call. It positions itself as the entry point, which distinguishes it from siblings like ask_rightshold and check_license, though the operative verb ('returns') is somewhat 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?

It gives a clear condition: 'Call first if you are new to Rightshold,' and shows two concrete invocation modes (checking a license or asking a plain-English question). It stops short of naming which siblings to use instead once the agent is familiar, so it is strong context without explicit alternatives.

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

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

Goes well beyond the annotations: it discloses the privacy contract (only aggregate counts and average scores are published; free text and contact are read by the team and never published) and the auth requirement ("No account needed"). That is exactly the kind of non-obvious consequence an agent needs before sending user-authored text.

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

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

Three sentences, zero filler, front-loaded with the purpose and followed by the payload and the privacy terms. Every clause 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?

An output schema exists so return values need no explanation, and the description covers the remaining burdens: what to send, which fields are optional, that no account is required, and how the submitted data is treated. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is only 17%, so the description has to compensate, and it does — it maps each field (topic, satisfaction 1-5, optional ease 1-5, optional free text, optional contact) and marks which are optional. It omits the `kind` agent/human parameter, which is only documented inside the schema, so it is strong but not complete.

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?

Delivers a specific verb and resource — submit feedback about Rightshold — and enumerates the exact payload (topic, satisfaction, optional ease/free text/contact). No sibling tool does anything similar, so it is trivially distinguishable from the read/verify/lookup tools in the list.

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?

"Tell the Rightshold team what is missing, broken or worth more" implies the motivating situations and "No account needed" removes a likely blocker, which is real context. However, it names no alternatives and gives no when-not guidance (e.g. use a support/status tool for outages), so usage is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so safety is covered. The description adds genuine context beyond that: which keys the signature is checked against, that the ledger hash is confirmed, and that a valid manifest 'shows what was answered and when' while not being a license grant. No auth or rate-limit detail, but no contradiction either.

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

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

Two dense sentences with the core verification steps front-loaded, followed by the optional-parameter conditional and the interpretive caveat. Every clause adds information; nothing is 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?

An output schema exists so return values need not be explained, and the description covers the verification pipeline, the conditional parameter behavior, and the semantic meaning of a valid manifest. It does not state how a failed or tampered manifest is surfaced, a minor gap for a verification 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 low (33%), so the description must carry weight, and it does for the key optional parameter: 'with deliverable_sha256, also that it covers those exact bytes' explains both the condition and the extra verification performed. The required manifest and signature parameters are only implied by prose, not explicitly defined, which keeps this below a 5.

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 (check/verify) plus the exact resource (a rights manifest) and enumerates the three things being validated: signature against Rightshold's issuer keys, ledger hash recording, and byte-level coverage when deliverable_sha256 is supplied. It is clearly separable from siblings like issue_rights_manifest (issuance) or ledger_verify (raw ledger check).

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

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

It gives clear context for when the tool applies and an implicit exclusion via 'it is not a license grant', steering the agent away from treating a valid result as licensing permission. It stops short of naming the alternative sibling (e.g. check_license) that should be used for that question, so it is short of the 5 bar.

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