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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial behavioural context: the scoring inputs (near-copies, bursts, link-only posting), that missing profile/follow/relay lists add but never flag alone, that quiet authors are only counted, that established signs lower the score, and that it performs extra lookups on top candidates. These are meaningful operational traits an agent cannot infer from the schema or 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 core purpose is front-loaded and the dense parentheticals all carry scoring-relevant information rather than filler. It is somewhat run-on and could be broken into shorter sentences, but no sentence is expendable.

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 heuristic scoring tool with five fully documented parameters and no output schema, the description covers the mechanism, the interpretation caveats, and the lookups it triggers. It stops short of describing the returned structure (e.g. what fields accompany each author's score/reason), which would help since no output schema exists.

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

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

Schema description coverage is 100%, so all five parameters (top, hours, kinds, relay, sampleLimit) are already documented with ranges and defaults. The description adds only a soft hint about the 'recent window' corresponding to the time filter, so the baseline 3 applies.

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

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

The description states a specific verb and resource: it lists authors in a recent window whose behaviour looks like spam or abuse, with scored reasons. The scope (behavioural signals, highest score first) is unambiguous. It does not, however, distinguish itself from plausible siblings such as author_report or trust_score, so it stops short of a 5.

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

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

Usage is implied through 'A triage aid, not a verdict' and the note that missing data alone never flags an author, which frames how to read the output. There is no explicit when-to-use versus when-not, and no alternative sibling (author_report, trust_score) is named for the adjacent questions an agent might have.

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, open world). The description adds genuinely non-obvious behavior: results are computed over a sample of the newest events, capped at sampleLimit, so counts are approximate rather than exhaustive, and it flags heuristic outputs like possible spam or throw-away keys. It does not note sampling error magnitude or the merge semantics across multiple relays.

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

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

One front-loaded sentence with the verb first and the sampling caveat last; nothing is wasted. It is dense and would read better as a short list, but every clause carries real information.

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

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

With no output schema and six all-optional parameters, the description largely compensates by enumerating exactly what the report contains. Remaining gaps are minor: it does not explain how the multi-relay merge or default-relay selection affects the report, though the schema covers those mechanics.

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 every parameter (tags, hours, kinds, relay, relays, sampleLimit) is already documented in the schema. The description only echoes sampleLimit and the time window, adding no syntax or format detail beyond the schema, which matches the baseline for full schema coverage.

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

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

States a specific verb and resource ('Analyses a sample of recent events') and enumerates seven concrete output metrics, which lets an agent place it as the aggregate-analytics tool rather than a raw lister. It does not name or contrast with the nearest sibling (author_report, count_events), so overlap on 'most active authors' has to be inferred.

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

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

Usage is only implied: the metric list tells the agent this is for a broad activity overview rather than a targeted query, but there is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives like author_report or count_events.

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 real behavioral context beyond that by scoping the result to 'this relay' and by explicitly warning that 'first/last' mean the oldest/newest events the relay returned, not account age. It stops short of describing merge behavior when several relays are supplied, which the schema hints at.

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

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

Two sentences, front-loaded with what the report contains, followed by the single most confusable return-value caveat. The escaped-quote clause is slightly awkward to read but it carries unique information rather than filler.

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

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

With no output schema, the description must carry the return-value burden, and it does name the report's major sections (profile, follow count, relay list, recent events) plus one interpretive caveat. Missing pieces such as pagination or the multi-relay merge output shape are minor for a read-only report tool.

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

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

Schema description coverage is 100%, so the limit/relay/relays/pubkey semantics are already fully documented, including the relay-override rule and merge behavior. The description adds only indirect cues ('on this relay', the 'first/last' caveat) and says nothing about limit or the multi-relay merge, so the baseline 3 is correct.

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 act ('looks at one public key') and enumerates exactly what the report contains: kind-0 profile, follow count, relay list, and recent events. It is clearly per-author rather than relay-wide, so the agent can place it against relay_overview or recent_events, though the link to activity_report is framed as similarity ('same analysis as') rather than as a distinction.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The only routing hint is the passing reference to activity_report and the phrase 'on this relay', which implies scope but does not tell the agent which of the twelve siblings to pick for a given question.

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 the description adds genuinely non-obvious behavior: busy relays return only newest events so samples aren't compared directly, failing relays are reported while others still compare, and '0 events' comes with the relay's stated reason. This is strong context beyond the annotations, though return shape details are not 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?

Front-loaded with the core comparison and the propagation value proposition, then supporting caveats. It is one dense paragraph and the em-dash aside is slightly rambling but every clause carries useful information.

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

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

With no output schema and read-only annotations already covering safety, the description still explains what the agent will learn (share of events that reached each relay), how failures and zero counts are handled, and sampling caveats. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% so baseline is 3, but the description adds meaning: the reference relay's events are what get looked for on the others, defaulting to the first configured relay, and the reference contributes at most 200 events to the propagation check. This clarifies the sampleLimit interaction 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?

Names a specific verb (compares) and resource (configured relays) and enumerates the dimensions compared: NIP-11 info, latency, activity, kinds, and propagation. This is clearly differentiated from siblings like relay_overview because it emphasizes the side-by-side propagation check across multiple relays.

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?

Describes the mechanics and defaults (first configured relay as reference) but never explicitly says when to pick this over relay_overview or nostrclaw_status, nor when not to use it. Usage is implied by the propagation emphasis rather than stated.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered; the description adds real behavioral context beyond them — the NIP-45 mechanism and explicit fallback messaging when a relay lacks COUNT support, which the agent would otherwise have to discover at runtime.

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, zero filler, with the core action front-loaded and the protocol/fallback caveat immediately after. Every clause earns its place.

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

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

With strong annotations and a well-documented 6-parameter schema, the description supplies the missing pieces an agent needs: the counting mechanism and the unsupported-relay behavior. The only minor gap is not hinting at the shape of the returned count/merged-relay result, which is largely self-evident for a count 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 83%, so most parameters (tags, kinds, relay/relays, sinceHours) already carry their own documentation with examples; authors is the only one left bare. The description adds no filter syntax or constraint detail beyond what the schema states, 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?

Specific verb (counts) + resource (events matching a filter) with a distinguishing trait: it uses NIP-45 COUNT and does not download events, which separates it from fetch-oriented siblings like recent_events or relay_overview. It never names a sibling explicitly, so differentiation is inferable rather than stated.

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

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

The phrase 'without downloading them' implies when to prefer this over retrieval tools, but no alternative tool is named and no when-not condition or prerequisite (e.g. needing a configured relay) is spelled out in the description. Usage is implied rather than instructed.

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, openWorld, non-destructive, so the safety profile is covered. The description adds substantive behavior beyond that: the count is derived from referencing events, capped at 500, and broken down by reaction type and distinct reactors — meaningful semantics an agent cannot get from 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?

A single dense sentence with the core resource front-loaded and no filler. It is slightly overloaded with the enumeration plus the breakdown clause, but every element 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?

There is no output schema, so the description must convey the return shape — and it does: counts of four interaction types, a reaction breakdown, and distinct-reactor counts, with the 500-event cap. Remaining gaps (pagination, behavior when the relay doesn't hold the event) are minor for a read-only lookup 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 coverage is 100% with only 2 parameters, and the schema already documents the id format and the relay URL/default constraint. The description adds no parameter-level detail (e.g., what happens if the id is malformed or the relay lacks the event), 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 names a specific resource (one event) and enumerates exactly what is computed: replies, reactions, reposts, zaps plus reaction breakdown and distinct reactor count. It is clearly distinct from generic siblings like recent_events or count_events, though it never explicitly names an alternative to differentiate against.

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?

"For one event" implies the usage context (single-event lookup vs. aggregate/list tools), but there is no explicit when-to-use guidance, no when-not, and no pointer to a sibling for broader queries. Usage is inferable but not stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds real behavioral context beyond them: the 20-id cap and, importantly, that only kind and age are returned, not content — valuable given there is no output schema.

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

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

Three short sentences, front-loaded with the core operation, then the return scope, then the use case. Nothing is redundant or 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?

With no output schema, the description carries the burden of conveying return shape and does so at a high level (per-relay presence, kind, age). It omits output formatting details and behavior when fewer than two configured relays exist, which is a minor gap for a read-only lookup 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 coverage is 100%, so both parameters (ids, relays) are fully documented in the schema, including hex/note1 formats, the max of 20, wss:// relays, minimum of 2, and the default. The description largely restates the 20-id limit and 'configured relays' constraint rather than adding syntax the schema lacks.

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: for up to 20 event ids, report which configured relays hold each one. The output content ('kind and age only, not the content') makes the purpose unmistakable and separates it from relay_overview and compare_relays.

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 the two concrete decision contexts: checking whether a note spread to other relays, and whether a relay dropped something. However, it names no explicit alternative or exclusion (e.g., when to use compare_relays or relay_overview instead).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond those booleans by disclosing that signing is not enabled, which tells the agent what operations are impossible on this server, plus that the output covers allowed relays and limits.

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

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

A single sentence, front-loaded with what the tool reports, then the three content categories. Every clause earns its place and nothing is padded or repeated from the schema.

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

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

With no output schema and no parameters, the description carries the burden of telling the agent what comes back, and it does enumerate the returned content (relays, limits, read-only status). It stops short of describing the shape or format of the response, which is a minor gap for a diagnostic tool.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate and no misleading parameter language. No further param detail is needed or possible.

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 ('Shows') and resource ('how this server is configured') and enumerates the concrete content: relays it may talk to, its limits, and read-only status. This is clearly distinguishable from data-oriented siblings like relay_overview or recent_events, though it never names or contrasts with any sibling explicitly.

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

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

Usage is implied rather than stated: an agent can infer this is for inspecting/verifying server configuration and capabilities, but there is no explicit when-to-use, when-not-to-use, or named alternative. With eleven sibling tools and no routing guidance, an agent must reason about fit on its own.

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

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, so the safety profile is done. The description adds genuinely non-obvious behavior: content is cleaned of hidden characters and truncated, signatures are verified, and bad-signature events are silently dropped but counted. That post-processing disclosure is valuable context beyond structured fields.

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

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

Three tight sentences, front-loaded with purpose, then filters, then processing caveats. No filler or repetition of the schema.

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

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

For an 8-parameter read tool with no output schema and annotations already covering safety, the description covers purpose, ordering, filtering and the cleaning/verification pipeline. It could say more about how dropped events are reported or how multi-relay results are surfaced, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents tags, kinds, limit, relay/relays, authors, sinceHours and maxContentChars in detail. The description only restates a subset (kind, author, age) and adds the ordering fact; it contributes little parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('fetches recent events from a relay'), plus ordering ('newest first') and the filter axes (kind, author, age). It is clearly distinguishable from count_events or relay_overview by implication, but it never names a sibling to sharpen 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?

The phrase 'optionally filtered by kind, author and age' implies the intended use case, but there is no explicit when-to-use versus alternatives such as count_events (counting) or compare_relays (relay comparison), and no exclusions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond them: that statistics are only present 'when the relay publishes them', so the agent knows that section can legitimately be absent rather than a failure. It does not discuss latency thresholds or error shapes, keeping it at a 4.

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

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

One front-loaded sentence that leads with the framing ('First look at a relay') and then lists outputs in priority order. The parenthetical enumerations are dense but each item is informative; only the nested parentheses make it slightly heavy to parse.

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

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

With no output schema, the description carries the return-value burden and discharges it well by listing the three result groups and flagging that stats are conditional. For a single-optional-parameter read tool this is nearly complete; only error/timeout behavior is left unstated.

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

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

Schema coverage is 100% and the single parameter already documents the wss:// URL format, the configured-relay constraint, the default, and a pointer to nostrclaw_status. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description names a specific resource (a relay) and enumerates exactly what the tool returns: reachability/latency over HTTP and WebSocket, the NIP-11 document, and public statistics. That is far more than a restated title. It stops short of naming a sibling, though the singular 'a relay' implicitly contrasts with multi-relay tools like compare_relays.

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?

'First look at a relay' implies this is the entry-point/diagnostic call before deeper tools, which is genuine usage context. However, no alternative is named and no when-not condition is given, so the routing guidance remains implied rather than explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), but the description adds substantial non-obvious behavior: how the verdict is derived (what the key does to others, repeated text, link density, bursts, web-of-trust), the explicit rule that behaviour outweighs trust, and the distinction between 'automated' and 'promotional-bot.'

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 core purpose is front-loaded, but the remainder is a dense wall of text with nested quotes and semicolon-chained category definitions that is hard to parse. The information is relevant, yet the structure could be broken into clearer clauses without losing content.

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

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

With no output schema, the description does explain what the tool returns (per-distinct-person verdicts) and how they are computed, which is the key burden. It stops short of describing the result shape or ordering, but the essential semantics are present for a 4-parameter triage 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning for `trusted` ('give your own key... for a much better signal') and reinforces that `maxAuthors` prioritizes replies ('replies first'). It does not add format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('who replied to it, reacted to it or reposted it' for 'one note') and scopes the output (a per-person verdict). This is clearly distinguishable from sibling tools like author_report, account_triage, and event_engagement.

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

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

Gives clear operating context: it is 'a triage aid, not a verdict,' replies are examined first, and supplying your own key in `trusted` yields 'a much better signal.' It does not, however, name when to prefer it over siblings such as account_triage or event_engagement, so no explicit exclusions.

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/openWorldHint, so the safety profile is covered. The description adds real context beyond that: the caveat that rings can form, that 'unknown' means nothing vouches for it here rather than 'bad', and that it is an aid not a verdict. It stops short of describing return shape or latency/cost of querying many relays.

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

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

Front-loaded with the core purpose before the scoring breakdown and caveats. The long middle sentence listing the five signals is dense but every clause earns its place; nothing is redundant 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 read-only tool with no output schema, the description explains inputs, defaults, and the semantics of an 'unknown' result. It does not describe the return format or score range, which is the main remaining gap given there is no output schema to fall back on.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the scoring weight of `trusted` ('a trusted key following it counts most') and reinforcing the omit-`pubkeys` behavior, adding interpretation the schema alone does not provide.

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 ('Scores how much the network vouches for keys') and then enumerates the exact signals used, so the agent knows precisely what the tool computes. It is clearly distinct from siblings like account_triage or author_report.

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 covers the two invocation modes: pass `pubkeys` to score given keys, or omit them to examine the NEW keys of a recent window, and explains the role of `trusted`. It gives clear operating context but never names an alternative sibling tool for adjacent questions.

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