Patina

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

Beyond the read-only/idempotent annotations, it explains the return shape (pass, reason, found), the critical 'no profile exists' behavior treated as UNKNOWN, and the meaning of score bands and the heavy weight of age. This adds substantial context not available in 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 long but each sentence earns its place by explaining Patina's meaning, limitations, and edge cases. It is well-structured and front-loaded with the core intent, though slightly more verbose than strictly necessary.

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 decision tool with no output schema, the description covers the return format, the unknown-profile case, the meaning of scores, and the limitations of the signal, making the tool self-sufficient for correct invocation and interpretation.

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 covers all parameters, but the description adds that at least one of min_score or min_years is required (not enforced in schema), explains the 0-100 scale and what different bands mean, and clarifies that min_years refers to the oldest provable signal.

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

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

The description opens with 'Decide whether somebody clears a trust bar, as a plain true or false,' which is a specific verb and resource. It further states this is the right tool for gating decisions, clearly distinguishing it from siblings like get_patina_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?

Explicitly provides example gating questions ('has this person been verifiably around for at least five years'), states 'This is the right tool for gating decisions,' and warns that Patina is the wrong signal for proof-of-personhood, giving actionable when-to-use and when-not-to-use 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?

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral detail: return contents (score, per-component breakdown, provable years, corroborating platforms, offline-verifiable attestation), the meaning of found:false for unknown usernames, and limitations (doesn't prove uniqueness/liveness). This adds significant context beyond the annotations and contradicts nothing.

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 long but highly information-dense, covering the scoring bands, what the score means, usage guidance, and an edge case. It is front-loaded with the main purpose in the first sentence. While a few details (e.g., score band descriptions) could be trimmed, every sentence serves to clarify the tool's behavior and selection criteria.

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 fully explains what the tool returns (score breakdown, attestation, found:false behavior) and covers edge cases (unknown usernames) and exclusions (not proof-of-personhood). The domain concept is sufficiently explained for an agent to correctly assess relevance. Complete for this level of 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?

The schema defines the single username parameter with a clear description including the URL format (patinadata.xyz/u/<username>). The tool description mostly reiterates 'by their Patina username' without adding new semantic details. Since schema coverage is 100%, 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 clearly states 'Look up a person's full Patina score by their Patina username' and goes on to explain the scoring scale and what the score represents, distinguishing it from sibling tools like check_threshold. This is a specific verb+resource with clear scope, not vague or tautological.

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 provides when-to-use guidance: 'Call this when you want the whole picture...' and contrasts it with an alternative: 'If you only need a yes or no about whether somebody clears a bar, call check_threshold instead.' It also states when NOT to use it (not for proof-of-personhood). This leaves no ambiguity about tool selection.

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?

Beyond the readOnlyHeader and idempotent annotations, the description richly discloses behavioral traits: it deliberately never returns the Patina username or linked platforms to prevent de-anonymisation, explains why some platforms are unsupported, and details the scoring bands. This far exceeds the safety profile provided by 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 long but each sentence adds substantive value: privacy rationale, scoring thresholds, supported inputs, and limitations. It is well-structured with clear sections, though it could be slightly more compact 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?

No output schema exists, but the description fully covers the return value ('only three things') and interprets all score ranges with real-world context. It also addresses edge cases (unsupported platforms, email refusal, handle formats), making it comprehensive for an agent to use 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?

The schema already documents both parameters with full coverage. The description adds valuable semantics: accepted handle formats (bare, @handle, URL), platform-specific examples, and the significance of source restrictions. This augments, rather than repeats, the schema, meriting above-baseline credit.

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 clearly states a specific verb and resource: resolve a platform handle to a Patina score. It explicitly lists supported sources (github, instagram, linkedin) and distinguishes itself from siblings like check_threshold and verify_attestation by clarifying its unique scope of handle-to-score lookup.

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 provides clear when-to-use context ('Find out whether the person behind a platform handle has a Patina score') and explicit exclusions (unsupported platforms, email refusal, forbidden requests). It does not name sibling alternatives directly, but the context signals make the distinction clear, so a slight deduction for missing explicit alternative references.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses key behavior: it returns the recovered address, the published address, and a match boolean, rather than a simple yes. It also explains the design rationale (avoiding self-trust), which is valuable context not present in 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 well-structured: it front-loads the purpose, then delivers a crucial caveat and explanation. Although longer than average, every sentence earns its place, and the logical flow from 'what' to 'why not' to 'how it works' is efficient and clear.

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 fully explains the return values and behavior. It also covers usage guidelines, the trust model, and the alternative offline verification path, making it self-contained and complete for an agent to decide whether and how to invoke the 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 input schema already provides 100% coverage with descriptions for both message and signature, including the 'exact message, newlines and all' and '0x-prefixed' details. The description merely references these parameters without adding new semantic meaning, so the 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 opens with a specific verb and resource: 'Check whether a Patina attestation really was signed by Patina.' This clearly distinguishes the tool from siblings like get_patina_score or check_threshold, and explains the exact verification function.

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 provides explicit guidance on when to use the tool and when not to, stating 'you do not need this tool, and where you can, you should not use it.' It names specific alternatives (viem's recoverMessageAddress, ethers' verifyMessage) and explains the reasoning, making the guidance actionable.

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