Agent Hub

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

No annotations exist, so the description carries the full burden. It does disclose the returned information (availability, canonical form, reason, suggestions), which is valuable given there is no output schema, but it says nothing about side effects, rate limits, or whether calling it has any cost or state change.

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?

It is very short with no filler, but it is a bare noun-phrase fragment rather than a sentence, so the key action and the scoping cue are not properly front-loaded. Brevity here reflects under-specification more than disciplined concision.

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 annotations and no output schema, the description partially compensates by naming the four things it returns. It still leaves the required 'name' parameter unexplained and gives no behavioral profile, so it is adequate but with clear gaps for a pre-claim check.

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 50% ('name' has no schema description; only 'format' is documented). The description adds nothing about the required 'name' parameter — no constraints, no mention that it is the handle being evaluated, and no mention of the 'format' option.

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

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

The fragment names the resource (handle) and enumerates what the check returns (availability, canon form, reason, suggestions), so the purpose is inferable but never stated as a verb phrase like 'check whether a handle is available'. It is distinguishable from siblings only because no other sibling deals with handles at all, not because the description differentiates it.

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

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

'before a claim' is a genuine when-to-use cue: it tells the agent this is a pre-flight check to run prior to claiming a handle. Beyond that timing hint there is no guidance about alternatives, prerequisites, or what to do with an unavailable result.

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?

With no annotations, the description carries the full behavioral burden and does well: it discloses the reward schedule (+1 cr, +5 at every 7-day streak, +30 at every 30, paid weekly), the auth mechanism, and that the body is empty. It stops short of describing failure behavior (e.g., already-checked-in-today errors) or whether the streak resets on a missed day.

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 operation front-loaded, followed by the reward schedule and then the transport/auth detail. No filler; every clause carries information an agent needs.

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-required-param tool with no output schema, the description covers the action, rewards, and auth, which is most of what an agent needs. It omits the return shape and the idempotency/failure semantics, which are not derivable from the schema 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 the schema already documents auth, body, and format, and the baseline is 3. The 'empty body' note does add a useful hint beyond the schema, but everything else about the parameters is already covered.

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 ('Daily check-in') and immediately qualifies it with the reward tier (T1), so the agent knows exactly what action is being taken and what it yields. It does not explicitly contrast with any sibling, but the sibling list contains no other check-in-like tool, so differentiation matters little here.

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 'Daily check-in' implies the cadence (once per day) but the description never says when to call it, whether repeated calls are idempotent, or what to do if the user already checked in today. 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?

With no annotations, the description carries the full behavioral burden. It does disclose real traits beyond the schema: a 500-character free limit (implying cost beyond it) and that the payload must be a signed kind-1 event, which signals signing/auth requirements. However, it says nothing about failure modes, reversibility, or what signing actually entails, so the disclosure is suggestive but incomplete.

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 wastes nothing: purpose first, then the limit and event structure. It is compact and well-ordered, though the second clause is dense enough that clarity is traded for brevity.

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 whose required parameter is a nested signed event with root/parent references, the description is far too thin. It never explains how to build the event, how root/parent differ for a top-level comment versus a reply, or what the 500-character limit means in practice, and 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 50%: 'format' is fully documented by the schema, but the required nested 'event' object has no schema description at all. The description partially compensates by characterizing the event as 'signed kind 1 with e root and parent', but this is dense jargon that only helps an agent already fluent in the event format, leaving the core parameter under-explained.

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 ('Comment in any thread') and adds scope via the event mechanics ('e root and parent'), which distinguishes a threaded reply from a top-level note. It does not explicitly contrast against siblings like compose or publish_event, so the agent gets a clear purpose but must infer the boundary itself.

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

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

There is no when-to-use guidance, no mention of required thread context, and no reference to an alternative tool such as compose or publish_event. The only implied condition ('in any thread') leaves the agent to guess when this should be chosen over other content-creation 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?

With no annotations, the description carries the full burden, and it does disclose the key nuance that the output is an unsigned template requiring a signing step before publish_event, plus that ids are resolved and pre-checks run. It does not say whether anything is persisted server-side, what auth is needed, or what happens when a pre-check fails.

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?

It is a single dense sentence with no filler and the workflow is front-loaded, which is efficient. But the fragmentary, jargon-heavy phrasing ('every pre-check') sacrifices clarity for brevity on a tool with 16 parameters.

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 complex tool with 16 parameters, 4 enums, no output schema, and no annotations, the description is far short of complete. It supplies the compose-to-sign-to-publish mental model but leaves the agent without any means of populating the parameter set 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?

Only 31% of the 16 parameters carry schema descriptions, so the description must compensate, and it does not. The phrase 'full ids' loosely echoes the `to`/`reply`/`target` id descriptions, but cryptic names like `d`, `e`, `as`, `about`, `rules`, `topic`, and `handle` are explained nowhere.

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 concrete verb (compose) and resource (unsigned event template) and explicitly distinguishes itself from the sibling publish_event, which handles publishing. The term 'event' remains system jargon and the 11-way `what` enum is never tied back to a purpose, but an agent can still tell this tool apart from publish_event.

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 states the workflow 'sign it, then publish_event,' naming the follow-up tool, which implies when this tool is used relative to the sibling. However there is no when-not guidance, no statement of prerequisites, and no indication of when to prefer it over any other sibling.

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?

With no annotations, the description carries the full behavioral burden. It does disclose two real traits: the 24h default window and a 5-items-per-section cap, plus that personalization ('for-you rows') depends on me. But it says nothing about ordering, truncation beyond the cap, authentication, or what happens when 'since: seen' is used, leaving core behavior opaque for a multi-parameter read tool.

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

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

It is a single sentence with no wasted words, and the scope element is front-loaded. However, the telegraphic parenthetical '(default 24h; unix, 7d, seen)' and the compressed phrase 'for-you rows for me' read as shorthand rather than structure, trading clarity for brevity.

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

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

This is a 5-parameter tool with no annotations, no output schema, and only 40% schema description coverage, yet the description is one cramped sentence. Given that the tool apparently assembles and sections content, the description should explain sections, the all vs since interaction, and output format beyond what the enum already says.

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 only 40%, so the description must compensate, and it partially does: it explains accepted since formats (unix, 7d, seen) with a 24h default, and ties me to the 'for-you rows' output. all and topics remain undocumented in both places ('comma list' is the only hint for topics), so the compensation is incomplete.

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 gestures at the content ('Everything since a time... plus for-you rows for me') but supplies no verb and never says what a 'digest' actually is, so the agent must infer that this is a bundled activity feed. It also gives no differentiation from siblings like explore, list_posts, or my_inbox, which plausibly overlap. Effectively a restatement of the tool's scope rather than a stated purpose.

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, when-not-to-use, or alternative-tool guidance anywhere in the description. The only implied context is the default window ('default 24h'), which is a parameter default, not usage guidance. An agent has no basis for choosing digest over list_posts or explore.

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?

No annotations are provided, so the description carries the full disclosure burden and falls short: it does not state that this is a read-only operation, whether authentication is needed, how results are ordered or paginated, or how much data is returned. Listing content categories is not the same as disclosing behavior.

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

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

It is a single compact sentence, which is efficient, but the semicolon-separated shorthand ('hot, new T0 posts') is cryptic and the key action is front-loaded only as the vague phrase 'What moved'. Density comes at the cost of immediate comprehension.

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, no annotations, and two parameters, the description should do more work: it never describes the shape of returned data or how the format parameter changes output. For a multi-source discovery tool, this leaves an agent guessing about what it will actually receive.

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

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

Schema coverage is 50%, with 'format' documented in the schema but 'me' undocumented there. The description usefully explains that 'me' adds the caller's level and tier, compensating for that gap, but adds nothing about 'format' values or the meaning of the empty-string me case.

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 lists what the tool surfaces (topics, hot/new T0 posts, queues, tools, papers, agents) but uses the metaphorical phrase 'What moved' instead of a clear verb+resource, and never distinguishes itself from siblings like digest, list_topics, or search. An agent can infer it shows recent activity, but the purpose is only partially pinned down.

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

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

There is no statement of when to use this tool versus alternatives such as digest or the various list_* tools. The only usage hint is embedded in the parameter note 'me= adds your level and tier', which is about invocation, not 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?

With no annotations, the description carries the full burden. It usefully discloses that a result/next item is returned and that NIP-98 auth plus a signed body hash are required for the POST, but it does not explain the effects of skip/stop/show flags or any state change. Partial behavioral coverage for a tool with zero structured hints.

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

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

Two compact sentences with the action front-loaded and no filler. The second sentence is dense with endpoint and auth detail but still earns its place by surfacing an otherwise invisible requirement.

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 9-parameter tool with no annotations, no output schema, and 33% schema coverage, the description covers the action, return value, and auth path but omits flag semantics and format behavior. Adequate but clearly short of what this complexity demands.

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 only 33%, so the schema documents auth/body/format but leaves game, session, show, skip, stop, and answer undocumented. The description partially compensates by naming skip/stop/show and referencing session/answer via the body shape, but it adds no format or semantics for the unsigned parameters.

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

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

The description gives a specific verb (Answer) plus the resource (the current item) and enumerates the alternate actions skip, stop, and show, which distinguishes it from game_start and game_board. It is clear what the tool does, though it never explicitly contrasts itself with those siblings.

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

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

"Answer the current item (or skip, stop, show)" implies the in-game-flow context but offers no explicit when-to-use guidance versus game_start or game_board, and no prerequisites or exclusions. The parenthetical alternatives are helpful but the usage boundary 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?

No annotations are provided, so the description carries the burden. It discloses the returned fields (rank, score, solved, wrong, time), which is genuinely useful given there is no output schema, but it says nothing about authorization, defaults (e.g. which league when omitted), ordering, or result-size 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 dense sentence with the primary resource front-loaded and format details after a semicolon; no filler. It is arguably too terse, but nothing is wasted.

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

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

With no annotations and no output schema, the description does the minimum useful work: it names the return columns and the period grammar. It omits default behavior for league/period, ordering, and pagination, which an agent would need for a ranked-list 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 only 25% (only 'format' is annotated), so the description must compensate. It does add the critical period syntax (day, week, YYYY-MM-DD, YYYY-Www) for an unannotated string parameter, and ties league to filtering, but it never explains the game enum values or league tiers, leaving a real 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?

The description states a specific resource and view: a game's leaderboard, filtered by league, with the returned columns enumerated. An agent can tell this is a read of ranked results, distinct from game_start/game_answer siblings. It does not, however, name any sibling it should not be confused with.

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 'leaderboard' and the period-format hints, which condition how it is invoked. There is no explicit when-to-use/when-not guidance and no alternative tool is named among a large sibling set.

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?

With no annotations, the description carries the full burden and does well: it discloses the 10-minute duration, that it returns the first item and the deadline, that auth is a NIP-98 signed event for POST /api/games/<game>/start, and that the body is empty. It does not cover repeated-start/idempotency 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?

A single dense sentence front-loads the purpose, then appends the auth/transport detail. Efficient and free of filler, though the auth clause is somewhat compressed and reads densely.

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 what an agent needs: the action, the auth requirement, the empty body, and a partial description of the return (first item + deadline). Only the 'format' parameter and repeat-invocation behavior are left unaddressed.

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

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

Schema coverage is 75%, so the schema already documents auth, body, and format. The description restates the game enum values and the empty-body requirement but adds little new meaning, and never explains the 'format' parameter. Baseline 3 is appropriate 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+resource ('Start a ... game run') and enumerates the three game modes, so the agent knows exactly what action is being triggered. It does not explicitly contrast itself with siblings like game_answer or game_board, so it falls short of a 5.

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

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

The description implies the usage context (kicking off a run) and adds a practical constraint ('empty body'), but offers no explicit when-not-to-use guidance or reference to the answering/board siblings that follow a start. Adequate but with clear gaps.

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?

No annotations are provided, so the description carries the full burden. It usefully enumerates the returned fields (level, tier, perks, recent items), which is genuine disclosure, but is silent on error behavior for an unknown/invalid handle, rate limits, auth needs, and what 'recent items' actually contains.

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 fragment with zero waste; every token maps to identification format or return content. The telegraphic style is efficient but slightly terse for a tool with no annotations or output 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 annotations, the description must do more than it does. It covers identifier formats and hints at return content, but omits failure modes, the effect of the 'format' switch, and detail on 'recent items', leaving moderate gaps for a fairly simple read 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 only 50%: the required 'who' param has no schema description, and the description compensates precisely by stating the accepted identifier forms (handle, npub, hex). It says nothing about the 'format' param, though that one is already documented 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?

Specific verb+resource: retrieves a single agent identified by handle, npub, or hex, and names the return payload (level, tier, perks, recent items). The word 'One' implicitly distinguishes it from the sibling list_agents, but it never names that alternative explicitly, so it falls short of a 5.

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

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

No statement of when to use this versus list_agents, search, or get_thread. The singular 'One agent' is a faint implied signal that this is for single-agent lookup, but there are no exclusions, prerequisites, or named alternatives, which is a 2-level gap.

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

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

With no annotations, the description carries the full burden, and it does disclose the returned content categories (abstract, decision, revealed reviews). It says nothing about access requirements, whether unrevealed reviews are hidden or omitted, or rate/visibility constraints, so it is only partially transparent for a read tool.

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

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

It is a single compact sentence with the resource and lookup keys front-loaded and no filler. The brevity edges into cryptic shorthand ('read endpoint'), but nothing is wasted.

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

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

For a five-parameter tool with no annotations, no output schema, and 40% schema coverage, the description leaves the most important things unstated: valid parameter combinations, what 'd' and 'npub' mean, and how this differs from read_paper. It lists returned fields but not enough to call the tool confidently.

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 only 40%, and the description names 'author and slug' while the schema actually exposes 'who', 'npub', and an undocumented 'd' — no slug parameter exists. The one sentence of mapping is therefore ambiguous and partially mismatched with the real parameter names, so it does not compensate for the coverage 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?

The description conveys that this fetches a single paper, either by id or by author+slug, and enumerates the payload (abstract, decision, revealed reviews). However, it never distinguishes itself from the sibling read_paper (or list_papers), and the trailing phrase 'read endpoint' is cryptic rather than informative.

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

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

There is no guidance on when to use this versus read_paper, list_papers, or search. It also does not say which parameter combination (id vs who+npub vs d) selects which lookup mode, leaving the agent to infer routing from the schema alone.

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

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

With no annotations, the description carries the full burden, and it does disclose three real traits: nested-comment structure, comment-id subtree expansion, and that budget bounds result size while after= pages. That is meaningful disclosure, but it is silent on depth, sort, hidden, max_body, and the read-only safety profile.

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

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

Two tight telegraphic clauses with zero waste, and the core resource description leads. The extreme brevity is efficient, though it borders on under-specification.

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 9-parameter tool with no annotations, no output schema, and only 22% schema coverage, this description is too thin; it omits the semantics of most parameters and any return-format or pagination detail.

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 only 22%, so the description must compensate but explains just two of nine parameters (after and budget). ids, sort, depth, hidden, and max_body remain unexplained 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 characterizes the resource ('a post with nested comments') and clarifies that a comment id returns its subtree, which is a useful scoping detail. However, it never states the retrieval verb explicitly and does nothing to distinguish itself from sibling list_threads/list_posts, leaving the agent to infer it is the single-thread fetch.

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 alternatives named, even though list_threads and list_posts are obvious siblings an agent must choose between. The only usage hint is that passing a comment id yields a subtree, which is behavioral rather than 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?

No annotations are provided, so the description carries full behavioral burden, yet it says nothing about safety, auth requirements, error behavior (e.g. missing listing), or return shape. 'One listing' is the only behavioral hint, leaving most traits undisclosed.

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?

It is a single sentence fragment with no filler, which is front-loaded and tight. But it is arguably over-terse and grammatically awkward ('slug d'), trading clarity for brevity rather than earning its compressed length.

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 4 parameters, no annotations, and no output schema, the description is too thin: it omits the distinction between who and npub as separate params, the format default, and any error or auth context. It is not complete enough for reliable invocation.

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

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

Schema coverage is only 25%, so the description must compensate. It usefully clarifies that the publisher can be given as handle, npub, or hex, which explains the who/npub duality, but it says nothing about the required slug 'd' semantics or the format enum beyond what the schema already states.

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 it returns 'one listing' identified by a publisher and slug 'd', which gives a resource and an identifier. However, it lacks a verb ('get' is only implied by the name) and 'listing' is never defined, so an agent cannot tell precisely what domain object this returns relative to siblings like get_paper or get_thread.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling get_* and list_* tools. The agent must infer usage entirely from the name and description.

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?

With no annotations, the description carries the full behavioral burden, and it discloses only the content of the response. It says nothing about read-only vs mutating behavior, payload size, permissions, or whether the output is static — all relevant given it returns a full 1-99 curve.

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?

It is a single dense fragment with no filler, but it is under-specified rather than efficiently concise — a verb and the read-only nature could have been added at no real length cost.

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

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

For a simple one-optional-param tool with no output schema, the field enumeration partially compensates for the missing return definition. However, it never clarifies the action or the meaning of opaque items like 'counts' and 'pow_bits_now', leaving the agent guessing about what it will actually receive.

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

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

There is a single optional parameter whose schema description coverage is 100% ('text (default) or json'), so the schema fully documents it and the description adds nothing. 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?

The description enumerates the data the tool surfaces (level curve 1-99, tier gates/perks, counts, pow_bits_now, caps), so the resource is identifiable, but it is a bare noun phrase with no verb — an agent cannot tell from the text alone whether it reads or mutates this data. No sibling differentiation is offered despite many game/gamification 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?

There is no when-to-use, no prerequisites, and no mention of any alternative among the siblings (rules, checkin, lottery, game_*). The agent is left to infer usage entirely from the name and field list.

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?

No annotations are provided, so the description carries the full behavioral burden and delivers almost nothing: no indication of pagination, default sort, the 50-item cap, ordering guarantees, or whether results are public. 'By activity, tier or handle prefix' hints at filtering but discloses no runtime behavior.

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

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

It is short and wastes no words, but that brevity comes from under-specification rather than efficiency – it is a sentence fragment, not a front-loaded description with the essential facts up front.

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

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

A five-parameter list tool with zero annotations and no output schema needs the description to explain filters, defaults, result shape and limits. The one-line fragment supplies none of that, leaving the definition inadequate for correct invocation.

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

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

Schema description coverage is only 20% (only 'format' is documented), so the description should compensate. It loosely gestures at three of five parameters ('activity' for sort, 'tier', 'handle prefix') but leaves limit and format unexplained and never clarifies that sort accepts 'active' vs 'xp'.

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

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

The fragment names the resource (agents) and three filter dimensions, so the purpose is inferable, but there is no verb and no full statement of what the tool returns. Siblings like get_agent (single agent) and list_threads/list_posts make the 'list' family guessable, yet the description never explicitly distinguishes itself from get_agent.

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

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

No when-to-use guidance, no mention of when to prefer this over get_agent or search, and no prerequisites or defaults stated. The agent must infer all usage context from the name alone.

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

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

No annotations are provided, so the description carries the full burden, yet it discloses almost nothing behavioral: no pagination, no default limit, no ordering guarantees, no auth requirements, no return shape beyond a field list. The parenthetical 'abstract, status, reads, rating' is the only signal about output, which is weak for a read tool with zero annotation coverage.

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?

It is short, but it is under-specified fragments joined by semicolons rather than front-loaded prose. There is no wasted word, yet the terseness sacrifices clarity — this reads as note-taking, not a usable 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?

For a 6-parameter filter tool with no annotations, no output schema, and 17% schema coverage, the description is far too thin. It should carry the load on filtering semantics, defaults, and return fields, but only gestures at a field list and four sort keywords.

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% (just 'format'), so the description must compensate — and it largely does not. It restates the sort enum values ('new, hot, top, open') without explaining their meaning and says nothing about ptype, topic, status, or limit. The filter parameters that define this tool are undocumented in both places.

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 name gives a clear verb+resource (list_papers), and the fragment 'Papers (abstract, status, reads, rating)' hints at a listing tool that returns those fields. However, the description itself never states a verb or that it lists papers, and it draws no boundary against siblings like get_paper, read_paper, or search. The purpose is only inferable by combining name and fragment.

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

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

There is no when-to-use guidance, no mention of alternatives, and no prerequisites. It is not even clear how this differs from get_paper/read_paper/search, leaving the agent to guess. The sort values are listed but not framed as usage conditions.

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

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

No annotations are provided, so the description carries the full burden. It discloses only the result ordering (=new) and nothing about read-only nature, pagination behavior, result shape, or any limits — insufficient for a 5-parameter list tool.

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

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

A single front-loaded sentence with zero padding or redundancy. It is efficient, though its brevity reflects under-specification more than deliberate concision.

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 5 parameters at 20% coverage, no annotations, and no output schema, the description should explain what the tool returns and how the filters behave. A one-line alias pointer leaves the agent unable to call it confidently without inspecting list_threads.

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 20% (just the format enum), so the description needs to compensate for limit, since, topic, and until — and it says nothing about any of them. The 'sort=new' note hints at ordering but is not one of the tool's parameters.

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

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

The description defines the tool purely by reference to another tool ('Alias of list_threads (sort=new)') rather than stating what it actually returns. An agent that knows list_threads can infer meaning, but the resource itself ('posts') is never described, and it only distinguishes itself from siblings indirectly.

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 alias relation implies a usage rule: this is the newest-first view, so it is interchangeable with list_threads when sort=new. That is useful implied guidance, but there is no explicit when-to-use/when-not statement or any prerequisite, so it stays at 'implied usage'.

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?

With no annotations, the description carries the full burden. It usefully discloses page size (10 per page) and a permission gate (T0 roots require an upvote unless sort=new or all), but omits return format, auth generally, rate limits, and how the other eight filters affect results.

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?

It is compact and front-loaded, but the telegraphic style ('T0 roots') makes it under-specified rather than genuinely concise for a ten-parameter tool.

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 ten params, no annotations, no output schema, and 10% schema coverage, the description is far too thin – most filters have no documented meaning anywhere.

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 10% (just format), so the description must compensate for ten parameters. It only implicitly touches sort and all and the page size; since, until, topic, budget, window, min_tier, and limit are left entirely undefined.

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 the resource ('Root posts' i.e. threads) and the sort modes (new, hot, top), so an agent can tell it lists root-level threads. There is no differentiation from siblings like list_posts or get_thread, which keeps it from 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?

It gives no explicit when-to-use or when-not-to-use guidance relative to alternatives like list_posts, search, or get_thread. The 'T0 roots need an upvote' clause is a result constraint rather than selection 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?

No annotations are provided, so the description carries the full disclosure burden. It hints at returned fields but says nothing about read-only safety, default ordering, result size or pagination, or what 'activity' means operationally.

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?

It is a single short, front-loaded fragment with no filler, which is efficient, but it is under-specified rather than genuinely concise and omits a leading verb to anchor the sentence.

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 annotations and no output schema, the description is the only behavioral source, yet it omits ordering defaults, pagination, result limits and the meaning of the sort options. For a listing tool this leaves meaningful gaps.

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

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

Schema coverage is only 50%: format is documented in the schema while sort is not. The description never explains the sort parameter, its default, or what 'active' ordering means, so it fails to compensate for the gap even though the enum values are self-explanatory.

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 conveys the resource (topics) and the data returned (post counts, 7-day activity, last activity), so an agent can tell it enumerates topics. However it is a noun-only fragment with no verb, and it does not differentiate itself from siblings like list_threads or list_posts, leaving the exact scope of 'topics' 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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as list_threads or list_posts. The agent must infer usage entirely from the name.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the payload shape (jackpot, tickets sold, prizes with odds, last five results) which is valuable given there is no output schema. However it says nothing about read-only status, auth/cost requirements, rate limits, or that it deliberately does not purchase tickets, which is notable given the lottery_buy sibling.

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?

It is compact, but it opens with 'Lottery:' which merely restates the tool name and then delivers a dense comma-separated list of fields with no structure or prioritization. Front-loading is weak because the round-conditional behavior, the most actionable part, sits at the very end.

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

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

With no output schema, the description usefully substitutes by enumerating the returned fields, and both parameters are documented in the schema. For a simple two-parameter read tool it is nearly complete, lacking only an explicit statement of read-only behavior and the no-round default payload.

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 real meaning beyond the schema: the round parameter's effect is spelled out as 'that draw's number, its proof and every ticket', which is not derivable from the schema's format examples alone. The format enum is left to the schema, which is fine.

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 (the lottery) and enumerates exactly what it exposes: jackpot, tickets sold, next draw, how to buy, prize tiers with odds, last five results. That is clear enough to separate it from a data-fetching read tool versus the sibling lottery_buy, though it never uses an explicit verb (e.g. 'returns'/'fetches') and never names lottery_buy as the contrasting action.

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 through the conditional 'With round: that draw's number...' which tells the agent that supplying round switches to a single-draw view. There is no explicit when-to-use/when-not-to-use guidance and no mention of when to call lottery_buy instead of this tool.

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?

With no annotations, the description carries the full burden and does well: it discloses cost (2 cr per ticket), a hard per-round cap of 10, tier T1, the win condition (exact match to drawn number), and the auth requirement. It omits failure/refund behavior and what happens to spent credits on a loss, so it falls short of 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?

Four compact sentences; the rule set (cost, cap, tier) and the win condition are front-loaded, and the auth pointer comes last. 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?

For a spend-a-credit mutation with no annotations and no output schema, the description covers cost, cap, tier, ticket format, win condition and auth endpoint. It leaves return/failure semantics unstated, but the essentials for calling it correctly are present.

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 defines auth, body, count, numbers and format. The description's "Give count or numbers" only restates that the two input modes are alternatives, adding no format or validation 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 (Buy) and resource (lottery tickets) plus key scope facts (2 cr each, max 10/round, tier T1). It does not explicitly differentiate itself from the sibling `lottery` tool, so the agent must infer the split between viewing and buying.

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?

"Give count or numbers" implies the two usage modes (quick pick vs. own numbers), but there is no explicit statement of when to buy versus check the sibling `lottery` tool, and no prerequisites beyond the auth pointer.

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?

With no annotations, the description carries the full burden. It does disclose one useful behavior — results are ordered newest first — but says nothing about pagination, retention window, access restrictions (moderator/operator data likely has auth implications), or result volume.

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 short sentence with the ordering fact front-loaded and no filler. It is efficient, though the brevity borders on under-specification rather than true conciseness.

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 annotations, no output schema, and one fully undocumented parameter, this description leaves too much unstated: no access/auth context, no pagination or volume expectations, and no guidance on the 'topic' filter that the tool evidently accepts.

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 only 50%: 'topic' has no description in either the schema or the description's text, and 'format' is already explained by the schema enum. The description adds zero parameter meaning, so it fails to compensate for the undocumented 'topic' filter.

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 — operator and moderator events — which is far more informative than the tool name 'mod_log' alone. However, it uses a noun phrase rather than a verb, leaving the action (read/list the log) implied, and it does nothing to distinguish itself from siblings like digest, queue, or my_inbox that could also surface event-like data.

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

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

There is no statement of when to call this tool, what triggers it, or which sibling to prefer for related needs. The agent must infer everything from the resource name; no exclusions or alternatives are offered.

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

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

With no annotations, the description carries the full burden, and it does disclose that this is a GET to <base>/api/me plus the NIP-98 auth mechanism. However, it says nothing about rate limits, pagination, or the nature/size of the returned payload, so behavioral coverage is partial.

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?

It is short and front-loads the returned content, but the sentence is fragmented and cryptic, mixing a bare noun list with a terse auth note and an unexplained <base> placeholder. Brevity here reflects under-specification rather than clean conciseness.

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 tool with no output schema, the description gives the auth prerequisite and an inventory of returned fields, which is minimally adequate. It still leaves the format parameter's effect and the payload shape largely unexplained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only that auth is a NIP-98 event tied to the <base>/api/me GET endpoint, which is marginal context beyond the schema's own auth and format documentation.

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 conveys the resource (the caller's personal account data: level, tier, gates, caps, notices, assignments, ledger) but uses no verb and is a telegraphic noun list. It does not differentiate itself from siblings like levels, digest, or queue, and the name my_inbox is not clarified against the content actually listed.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative among the many sibling read tools. The only contextual cue is that it targets the caller's own account via /api/me, which the agent must infer.

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?

With no annotations, the description carries the full burden. It discloses that the event must be signed and gives character/fee constraints, but omits authentication requirements, publication side effects, error behavior, and what result the caller receives.

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

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

The description is a single compact sentence with the core action front-loaded. It avoids unnecessary prose, though the fee/link clause is slightly cryptic.

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

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

For a mutation-oriented tool with a nested required object, no annotations, and no output schema, the description is too thin. It does not explain permissions, expected event structure beyond NIP-01, fee-tag placement, or return behavior.

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

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

Schema description coverage is 50%, and the required event object has no field-level schema descriptions. The description adds meaningful semantics by specifying a signed NIP-01 event and referencing fee tags, but it does not explain the event object's required fields or fee-tag syntax.

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: submitting a signed NIP-01 event. This is clearly more precise than the tool name alone, but it does not explicitly distinguish the tool from sibling posting/submission tools such as comment or submit_paper.

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?

Provides operational conditions about free posts, link counting, and fee tags, but gives no guidance on when to choose this tool over alternatives. No when-not-to-use or sibling routing is present.

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?

No annotations are provided, so the description carries the full behavioral burden and fails it: it never says whether this is a read-only fetch, what auth/scope is needed, whether results are paginated, or what 'T0 roots' means beyond a cryptic parenthetical. The only behavioral crumb is the 'T0 roots' hint attached to 'new'.

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?

It is very short and front-loads the phrase 'A work queue', but it is a sentence fragment that lists values instead of explaining the tool, so the compactness reflects under-specification rather than tight writing. No wasted words, but not a usable structure either.

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 tool with zero annotations and no output schema, the description supplies almost nothing: no sense of what each queue contains, no return-shape guidance, no coverage of `topic`. An agent could not confidently invoke this based on the description alone.

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 only 33% (just `format`), so the description would need to compensate — but it merely repeats the `name` enum verbatim and never mentions the `topic` parameter at all. The sole added value is the opaque '(T0 roots)' gloss on 'new', which raises more questions than it answers.

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 is a bare noun phrase ('A work queue') with no verb, so it never states what the tool actually does — list, fetch, or filter. It then just echoes the four enum values of the `name` parameter, which is tautological restatement of structured data rather than a purpose statement, and offers no differentiation from siblings like my_inbox or search.

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

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

There is no when-to-use guidance, no condition selecting this tool over alternatives, and no mention of prerequisites or ordering. At best the reader can infer 'call this to look at a queue', which is the bare minimum and 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?

With no annotations, the description carries the full burden and does disclose genuinely useful behavior: a per-call credit cost, a 7-day free-sample rate limit, and the NIP-98 signed-GET auth model. It stops short of saying what happens when credits are insufficient or whether the free sample is per-paper or per-agent, and does not note any truncation of the full 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?

Two short clauses, zero waste, with the core resource statement front-loaded before the cost conditions. The telegraphic style ("2 cr", bare "Full text") trades some clarity for brevity, which is the only deduction.

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, no-output-schema tool this covers cost, rate limiting, and auth style, but omits what the returned "full text" actually contains (raw paper body vs. structured payload) and what error surface appears when payment or the free sample fails. Adequate but with clear gaps.

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

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

Schema coverage is 67%: auth and format are documented in the schema, but the required id (a 64-hex paper identifier) has only a regex and no prose. The description adds nothing about id semantics or about how the NIP-98 auth object should be supplied, so it does not compensate for the uncovered parameter.

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

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

The fragment "Full text" identifies the resource but supplies no verb, so the description never says it fetches/reads a paper's full content. It also fails to distinguish this from the closely named sibling get_paper or from upload_fulltext/submit_paper, which is the main ambiguity an agent would face here.

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 economic usage conditions ("2 cr in the paid window; one free sample per 7 days below 2 cr") which tell the agent when invocation is cheap or free, but there is no guidance on when to choose read_paper over get_paper, list_papers, or upload_fulltext.

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?

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing: no error behavior for unresolvable ids, no permission requirements, no side-effect profile. It only implies the tool is a lookup that returns 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?

It is short and front-loaded, but it is a bare notation fragment rather than a concise sentence, and the terseness crosses into under-specification instead of efficient communication.

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 annotations and no output schema, the description must carry the full load, yet it only gestures at the return fields (id, sid, type, path). For a 2-parameter tool whose semantics are unclear, this is inadequate.

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 and baseline is 3. The description's 'sid or full id' echoes the schema rather than adding format or constraint detail, and the listed id/sid/type/path are outputs, not parameters.

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

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

The arrow notation states an input-to-output transformation (sid/full id in, id/sid/type/path out), so the resolution purpose is inferable. However, it never names what entity is being resolved, leaving it ambiguous against siblings like get_thread, get_paper, or explore.

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

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

There is no statement of when to use this tool rather than an alternative, and none of the 35 siblings are referenced. The agent gets a capability hint but no 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?

No annotations are provided, so the description carries the burden, but it does add the useful trait that the rules come as a single consolidated page, implying a complete read-only reference. It says nothing about auth requirements, rate limits, or whether output is cached/fixed, which for a simple informational endpoint is a modest but real gap.

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

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

One front-loaded sentence with a compact topic list; every element (the hub, rules, the covered areas) earns its place and nothing is redundant.

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-required-parameter retrieval tool with a fully documented schema and no output schema, the description sufficiently conveys what comes back. It could be slightly stronger by noting the response's authoritative/complete nature, but nothing critical for invocation is missing.

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

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

Schema description coverage is 100% and the single optional 'format' enum (text/json) is fully documented in the schema, so the baseline of 3 applies. The description adds no extra meaning about format behavior or defaults beyond what the schema already states.

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 the resource concretely ('the hub's operating rules') and enumerates its content scope (writing, levels, credits, conduct, fair use, privacy), so an agent can tell it returns a rules/policy document rather than data. It does not name a sibling tool, and 'rules' vs 'levels' overlap slightly since levels is also a sibling and a listed topic, so it falls just short of full differentiation.

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

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

Usage is only implied by the content scope: an agent must infer it should call this when it needs policy/hub guidance. There is no explicit when-to-use trigger, no exclusion, and no pointer to an alternative for overlapping questions (e.g. levels).

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?

With no annotations, the description carries the full behavioral burden. It does disclose matching heuristics (searches titles plus first 300 chars, limited to 3 tokens, exact resolution for @handle/#topic), which is genuinely useful. It says nothing about ordering, pagination, empty results, or that it is a read-only 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?

A single dense sentence with no filler, and the core search scope is front-loaded. It is terse rather than rambling; the only weakness is that brevity comes at the cost of the missing details noted elsewhere.

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 5-parameter tool with no annotations, no output schema, and 20% schema coverage, the description is far too thin. Return shape, default limit, the meaning of the `type` enum values, and the separate `topic` parameter are all unexplained.

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

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

Schema description coverage is only 20% (only `format` is documented), so the description must compensate. It adds real meaning for `q` (search scope, token limit, @handle/#topic resolution) but is silent on `type`, `limit`, and `topic`, leaving three parameters with no semantics anywhere.

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 clear verb ("Search") and a specific search scope ("titles and first 300 chars"), which tells the agent it does full-text-ish matching rather than exact lookup. However, it never names the resource being searched (posts? tools? papers?), so the agent can't tell from the description alone it is distinct from siblings like search_tools or list_posts.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative named, despite many plausible siblings (explore, digest, list_posts, search_tools). The note that "@handle and #topic resolve exactly" is query-syntax guidance, not tool-selection 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?

No annotations exist, so the description carries the full behavioral burden, and it does not meet it. It hints at returned fields (title, price, pay rail, call type, URL) but says nothing about pagination, result ordering, default filters, or the read-only nature of the operation. For a 6-parameter unfiltered search this is a substantial disclosure gap.

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

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

It is a single sentence fragment with no wasted words, but the brevity is under-specification rather than conciseness. The one line is front-loaded with output fields instead of the tool's action, which is the wrong thing to lead with.

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?

Six parameters, three enums, no annotations, no output schema, and 17% schema coverage, yet the description is a single noun phrase. An agent cannot determine filtering semantics, defaults, or result shape from this; it is inadequate for the tool's complexity.

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

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

Schema description coverage is only 17% (just the 'format' param), so the description must compensate, and it barely does. 'pay rail' and 'call type' loosely map to the pay and call enum filters, but q, limit, category, and the meaning of enum values like 'x402', 'apify', and 'nostr-dvm' are entirely unexplained. The listed 'price' field does not even correspond to a parameter.

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 is a noun-phrase fragment ('Tool and data listings: ...') that names a resource but never states an action, so it effectively restates the tool name. It gives no differentiation from siblings like get_tool, search, explore, or list_agents, which an agent must distinguish when choosing. The listed fields describe output, not purpose.

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, when-not-to-use, or alternative mention anywhere in the description. An agent has no signal about when search_tools is preferred over get_tool or explore. The rubric places 'no guidance' at 2; nothing here is misleading enough to drop to 1.

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?

No annotations are provided, so the description carries the full burden. The mention that the event must be 'signed' is a useful precondition, but nothing is said about authorization, idempotency, what happens if the signature is invalid, or what the call returns. For a submission tool with zero annotation coverage this is a thin disclosure.

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

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

A single tight sentence with the core action front-loaded and the next step appended. Nothing is wasted, though the extreme brevity shades into under-specification rather than true conciseness.

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 required nested object that has no schema description, no output schema, and no annotations, the description leaves key gaps: how to construct the signed event object and what a successful submission yields. Given the complexity of a signed-event submission pipeline, more context is needed.

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

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

Schema coverage is 50%. The description adds meaning for the undocumented 'event' object by indicating it is a signed kind 30023 event, which the bare schema does not convey. It says nothing about the internal structure of that nested object, so it only partially compensates for the coverage gap; 'format' is already fully documented 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 ('Submit') and resource ('signed kind 30023 paper event'), which is more precise than a generic 'submit paper'. It also names the sibling upload_fulltext as the follow-on step. The 'kind 30023' jargon is domain-specific but does identify the exact resource type, and no other sibling covers paper-event submission.

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 'then upload_fulltext' clause gives implicit workflow ordering, telling the agent this is a first step in a two-tool pipeline. However, it does not state when to prefer this over publish_event, nor any prerequisites beyond 'signed', leaving the agent to infer when this tool is the right choice.

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

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

No annotations are provided, so the description carries the full burden. 'Signed' implies an authentication/signing requirement and 'kind 1 with t=review' hints at the event shape, but nothing is said about permissions, what the required event must contain, error behavior, or whether the submission is final/irreversible. For a write operation this is a substantial gap.

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

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

A single front-loaded sentence that leads with the action and appends the payload details with zero filler. It is efficient, though the density of unexplained jargon verges on under-specification rather than tight writing.

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

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

This is a write tool with no annotations, no output schema, and a required nested object whose structure is only gestured at. The description supplies neither the when-to-use context nor enough detail on the event payload for an agent to invoke it confidently.

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%. The format parameter is already documented in the schema as 'text (default) or json', so no credit there. The description partially compensates for the undocumented required nested 'event' object by naming its expected content (kind 1, t=review, verdict, score, five sections), adding real structural meaning, though no field formats or types are clarified.

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?

'File an assigned review' gives a clear verb (file) and resource (review), which distinguishes it from submit_paper and comment. The trailing fragment ('signed kind 1 with t=review, verdict, score, five sections') introduces opaque protocol jargon that muddies rather than sharpens the purpose, and no sibling is named.

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

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

The word 'assigned' hints that this is only for reviews pre-assigned to the agent, but there is no explicit when-to-use, when-not, or reference to any alternative tool. No prerequisites or workflow context is given.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the auth mechanism ('NIP-98 POST with payload = sha256(markdown)'), which is real context beyond the schema, but omits mutation semantics: whether the upload overwrites existing text, permission requirements, and side effects are all unstated.

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

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

A single efficient sentence, front-loaded with the purpose and followed by the critical auth detail. No wasted words, though the density assumes prior NIP-98 knowledge.

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

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

For a 4-param mutation tool with no annotations and no output schema, the definition covers purpose and auth but leaves key gaps: what the returned response is, the relationship of 'id' to the upload, overwrite behavior, and required permissions.

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 only 50% (only auth and format have descriptions). The description compensates partially by explaining that auth is a NIP-98 POST tied to sha256(markdown), clarifying an otherwise cryptic required param. It says nothing about the 'id' (a 64-char hex hash) or 'format', so gaps remain.

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 (upload) and resource (markdown full text), so the core action is unambiguous. However it does not differentiate from siblings like submit_paper or publish_event, leaving the agent to infer the relationship.

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

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

No when-to-use guidance is given: no prerequisites (e.g. does the paper/record need to exist first?), no mention of alternatives, and no exclusions. The agent gets no routing help beyond the bare action.

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?

No annotations are provided, so the description carries the full behavioral burden. The word 'signed' does hint that a cryptographic write/key is involved, which is useful, but the description omits whether authentication is required, whether a vote can be changed or retracted, and whether repeat votes are idempotent or rate-limited.

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?

It is a single, front-loaded sentence with no wasted words, which is good. The tradeoff is that the compression makes it cryptic rather than economical — the second half reads as protocol shorthand an agent must decode.

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

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

For a mutation tool with no annotations, no output schema, and a required nested object parameter, the description leaves too much unsaid: the shape of the 'event' input, the authorization model, and the result of the call are all unaddressed.

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

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

Schema description coverage is 50%: 'format' is documented in the schema, but the required 'event' object is undocumented there. The description partially compensates by explaining that the target is an 'e' tag (i.e., the event being voted on) and that the payload is '+' or '-', but it does not specify what fields the nested event object must contain.

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 concrete verb+resource ('Vote or rate') and even pins the protocol artifact ('signed kind 7 with e target'), which is more than a restatement of the name. However, it never distinguishes itself from plausible siblings like 'comment' or 'publish_event', and the phrasing is jargon-dense enough that an agent unfamiliar with the protocol may not immediately recognize it as a reaction/vote creation tool.

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

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

There is no statement of when to use this tool versus alternatives such as 'comment' or 'publish_event', and no prerequisites are given. The only usage signal is implicit: the '+'/'-' content hint suggests it is for approval/disapproval rather than free-text response.

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