Patina

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

The description is unusually rich: it documents return fields (`pass`, `reason`, `found`), explains missing-profile semantics, and clarifies that Patina does not prove uniqueness/liveness. However, this contradicts the listed annotation `openWorldHint: false`. The description explicitly instructs that an absent profile be treated as UNKNOWN rather than false, which is open-world behavior, while the annotation tells the opposite global assumption. Per the instructions, a direct contradiction forces a score of 1.

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 longer than the typical tool note, but it is front-loaded with the core task and invocation requirements before the background on score bands and inputs. Some parts, like the exact point weights for Age, Continuity, Corroboration, etc., are arguably beyond what an AI agent needs to call the tool, making it less compact than a top-tier definition.

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

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

There is no output schema, but the description still tells the agent exactly what to expect (`pass`, `reason`, and `found`), how to handle the missing-profile case, and when Patina is not the right source. It leaves no ambiguity for correct invocation or interpretation of results.

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 all three parameters with clear descriptions (100% coverage). The description adds important non-schema context: that at least one of min_score or min_years must be provided, that the score is an indicator of provable history rather than popularity, and the meaning of the score bands. This extra context transcends the raw parameter list.

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 immediately states a concrete verb and resource: 'Decide whether somebody clears a trust bar, as a plain true or false.' It also clearly distinguishes this from a numeric lookup by explaining the boolean pass/fail return, making it easy to tell apart from get_patina_score and similar 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?

Explicitly says 'This is the right tool for gating decisions' and gives concrete examples like 'has this person been verifiably around for at least five years'. It also provides a clear when-not: Patina is wrong for uniqueness/liveness/personhood checks, which helps the agent route to another signal if 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?

Beyond the readOnly/idempotent annotations, the description reveals important behavior: unknown usernames return found:false as a normal result, not an error or negative evidence. It also clarifies what the score does and does not prove, which helps the agent set expectations.

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 lengthy but every sentence adds substantive context: scoring bands, component weights, caveats, and routing guidance. It is front-loaded with the core lookup purpose and then logically builds out the semantics.

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 lookup with no output schema, this description is remarkably complete. It explains the return value, interpretation, component breakdown, failure mode for unknown usernames, and the distinction from sibling tools.

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 username parameter is already described with a URL pattern. The tool description reiterates 'Patina username' but adds no additional parameter-level meaning beyond the schema, 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?

The description starts with a clear verb and resource: 'Look up a person's full Patina score by their Patina username.' It also defines what the score means and contrasts it with check_threshold, making the tool's specific role 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?

Explicit guidance is given: 'Call this when you want the whole picture' and 'If you only need a yes or no about whether somebody clears a bar, call check_threshold instead.' It also clearly states when Patina is the wrong signal, giving the agent helpful exclusion criteria.

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/non-destructive annotations, the description discloses critical behavioral limits: it returns only three values, never reveals the Patina username, never exposes connected platforms, and refuses unsupported inputs. This is exactly the kind of context annotations alone 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?

The description is long but well structured: core behavior, privacy constraints, exclusions, then score meaning. It is front-loaded and dense, though the score-band and weighting details go beyond what is strictly required to invoke the tool correctly.

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 specifies the return surface, accepted input formats, unsupported sources, privacy boundaries, and score semantics. An agent has all the information needed to decide whether and how to call 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 coverage is 100% and the schema already documents accepted handle formats and supported sources. The description adds useful interpretation context around scores and exclusions, but most of that is behavioral rather than parameter-specific, so the fully covered 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?

The description uses a specific verb and resource: 'Find out whether the person behind a platform handle has a Patina score' and immediately adds the privacy qualifier 'WITHOUT learning who they are.' It also separates itself from sibling tools by naming supported sources and what it deliberately never returns.

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 explicit when-to-use context (github, linkedin) and clear when-not-to-use exclusions (youtube, spotify, amazon, uber, Instagram, email) with reasons. It does not name sibling alternatives such as get_patina_score or check_threshold, so it stops short of the top routing bar.

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 that the tool returns the recovered address rather than a bare boolean, enabling independent comparison, and explains why that design exists. It also reveals expiration semantics: a genuine signature past expiresAt means the score was valid when issued and should be refetched, not that it was forged. Annotations already mark readOnly and idempotent; the description adds meaningful behavioral context without contradicting them.

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 longer than typical, but every sentence earns its place: core purpose, return value, why to avoid the tool, offline alternatives, and expiration caveat. It is front-loaded with the primary check and scoping, and the warning is presented as 'IMPORTANT, AND THE WHOLE POINT,' making the structure easy to follow. There is no filler or repetition.

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 no output schema, the description covers the return values, the rationale for the return shape, and the expiration edge case, giving an agent enough to decide whether and how to call it. It omits explicit error behavior for malformed signatures or mismatched addresses, but the strong 'do not use this tool' guidance reduces the impact of that gap. Overall it is highly complete for its 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 coverage is 100%, with both message and signature already described precisely ('newlines and all', '0x-prefixed'). The description restates the parameters but adds no new format or syntax details beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation 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?

The description opens with a specific verb and resource: 'Check whether a Patina attestation really was signed by Patina.' It clearly scopes the tool to signature verification and distinguishes it from siblings like check_threshold or get_patina_score by stating the return tuple: recovered address, published address, and match. This is unambiguous and immediately tellable apart from other 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?

Explicitly instructs when not to use the tool: 'you do not need this tool, and where you can, you should not use it,' and names offline alternatives (viem's recoverMessageAddress, ethers' verifyMessage). It explains the reasoning—server-side verification reintroduces trust in Patina—giving a clear condition for avoidance. This is strong usage guidance beyond any sibling description.

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