dpyc-oracle

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 real behavior beyond the schema: it fetches README.md and GOVERNANCE.md from the dpyc-community repo and assembles a context answer. It still omits freshness/caching behavior and confirms nothing about read-only safety or failure modes, but the sourcing disclosure is substantive.

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 sentences: the purpose is front-loaded in the first line and the data-sourcing mechanism follows immediately. Nothing is redundant or padded.

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

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

For a zero-parameter read tool with an output schema and no annotations, the description supplies the essentials an agent needs: what the answer covers and where it comes from. Return-value detail is legitimately offloaded to the output schema, so remaining gaps are minor.

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

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

The tool takes zero parameters, which is the baseline-4 case, and the empty schema (additionalProperties: false) leaves nothing for the description to clarify. No parameter syntax or format is needed here.

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 resource and scope: extended narration about DPYC, the Social Contract, and the Oracle, and names the mechanism (assembling content from README.md and GOVERNANCE.md). This distinguishes it as the general deep-dive tool, though it does not explicitly differentiate itself from topic-specific siblings like get_rulebook or economic_model.

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 'Extended' implies this is the comprehensive overview option rather than a targeted lookup, which gives an agent a usable signal. However, there is no explicit when-to-use/when-not guidance and no named alternative against a sibling set that clearly overlaps (get_rulebook, how_to_join, economic_model, network_advisory).

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 must carry the full behavioral burden, and it does supply real context: the vote is Lightning-funded and will verify npub membership, validate election activity, and record a payment proof. Most importantly it honestly discloses 'Not yet implemented', which is decisive for an agent. It stops short of describing permissions, payment amounts, or failure modes.

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 sentences, front-loaded with the core action and the vote's funding mechanism. No filler. The implementation-status caveat is placed second, which is arguably the right order for an agent scanning for feasibility.

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

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

An output schema exists, so return-value explanation is not owed. The unimplemented status is disclosed, which is essential. But for a 3-parameter mutation with zero schema coverage, the description leaves parameter semantics and payment/permission requirements unexplained, so it is only minimally complete.

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?

Three required parameters at 0% schema description coverage, and the description explains none of them. Only npub is obliquely glossed ('verify npub membership'); election_id and, critically, the vote value's accepted form are left entirely undefined, so an agent cannot construct a valid call.

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

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

Names a specific verb (cast) and resource (Lightning-funded ban vote) scoped to an active ban election. It is clearly distinguishable from siblings like check_ban_status, initiate_ban_election, and confirm_citizenship. Slightly held back because it never spells out the relationship to initiate_ban_election beyond the shared 'ban election' domain.

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 'active ban election' qualifier implies a precondition, but there is no explicit when-to-use guidance, no when-not-to-use, and no named alternative among the 30 siblings (e.g., check_ban_status before voting). Usage is inferrable 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 burden and does well: it declares the tool is free and unauthenticated (no credentials or side effects) and defines the edge case that unknown npubs return as not-banned rather than erroring. It stops short of stating latency/rate behavior or that it is a pure read, but the essential behavioral traits are covered.

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 purpose is front-loaded in the first sentence, followed by the lookup semantics, then auth cost, then usage context. Every line earns its place with no redundancy.

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

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

An output schema exists, so return values need not be described, and the auth/edge-case behavior is covered. The main remaining gap is the absence of any negative/permission note beyond "free, unauthenticated" for a tool with no annotations.

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 one parameter, and the schema has 0% description coverage, so the schema adds nothing. The description compensates partially by explaining what an unknown npub yields, but it never defines what an npub is or its format (hex vs bech32).

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 ("Check whether an npub is banned") and pins the scope to one community registry, which cleanly separates it from the broader lookup_member and from ban-action siblings like cast_ban_vote and initiate_ban_election. The added rule that unknown npubs are not banned makes the semantics unambiguous.

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

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

Gives a concrete usage context: "Used by operators during the cold path (credit purchases) to enforce community bans." That is a clear when-to-use, but no explicit when-not or named alternative (e.g. lookup_member for general member data) is 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 behavioral burden and does well: it enumerates the five verification checks and discloses the concrete write side effect (commits to dpyc-community/members/citizens/{npub}.json). It implies operator authorization via '(Operator-owned)' but does not state failure responses, idempotency, or whether a duplicate call is safe.

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

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

Front-loaded with the core action, then a flow-context line and a numbered verification list — structure is easy to scan. Slight redundancy between the opening sentence and the '(Operator-owned)' flow note keeps it from being maximally tight.

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

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

An output schema exists, so return values need not be explained; the description still covers flow position, verification steps, and the persistence side effect. For a 3-parameter mutation it is nearly complete, missing only explicit failure/error semantics and idempotency 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 0% and none of the three required parameters are defined field-by-field. The description lets the agent infer npub (the citizen's public key), challenge_id (issued by request_citizenship), and signed_event_json (the serialized signed event), but never states formats or expected encodings, so it only partially compensates for the documentation gap.

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

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

States a specific verb and resource ('Complete the citizen registration by submitting a signed Nostr event') and situates it precisely within the citizen registration flow, explicitly naming the sibling predecessor request_citizenship. An agent can distinguish it from request_citizenship and from other register_* tools without opening a schema.

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

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

Gives clear context: the Operator calls this on behalf of a patron after the patron has signed the challenge issued by request_citizenship. The trigger condition is unambiguous, though there is no explicit exclusion or list of failure/retry conditions that would tell the agent when NOT to call it.

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, so the description carries the full burden, and it delivers the two key traits: an auth requirement ('the request must be signed with the Authority's key') and the destructive effect ('removes the member file entirely'). It stops short of idempotency, failure behavior, or irreversibility guarantees, which would matter for a deletion 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?

Front-loaded with the action in the first clause, then the invocation context and the state-change consequence. No filler sentences and no repetition of the tool title.

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

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

For a mutating tool with no annotations, the description covers who may invoke it, what authorization is required, and what state change results, and an output schema exists so return values need not be explained. Only failure/edge-case behavior is left implicit.

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

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

Schema description coverage is 100% with only two parameters, both documented in the schema. The description reinforces the actor/key constraint on authority_npub but adds no format, syntax, or constraint information beyond what the schema already provides.

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

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

States a specific verb (Remove) and resource (Operator from the DPYC community registry), and the follow-up sentence clarifies the scope of removal (member file entirely, return to initial state). This clearly separates it from register_operator, update_operator and renounce_membership without opening any sibling schema.

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

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

States the triggering condition and actor: 'Called by an Authority when the operator leaves it or the Authority disowns the operator.' That gives real context for selection, but it never names the alternatives (e.g. renounce_membership for the member-initiated path) or says when not to call it.

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, and it discloses meaningful traits: free, unauthenticated, and explicitly that no rates/counts/revenue figures are returned. It does not describe response format or length, but the key behavioral boundary (a docent that quotes no numbers) is clearly stated.

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

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

Front-loaded with the core verb and resource, then efficiently adds scope, the no-numbers constraint, and access status. Every sentence earns its place with no redundancy.

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

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

For a zero-parameter narrative explainer with an output schema already present, the description covers purpose, scope, the critical 'no figures' caveat, and access requirements. Nothing needed to invoke it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case; the description correctly implies a no-input, purely narrative tool. There is no parameter detail to add.

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 ('Explain the DPYC Social Contract economic model — qualitatively') and immediately scopes the content to value flow, certification fees, and the Certification Chain cascade. The mention that rates/counts belong to the Authorities' pricing models implicitly distinguishes it from numeric siblings such as get_tax_rate.

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

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

Gives clear context for when to use it: for a qualitative explanation, with an explicit exclusion that it will not supply rates or revenue figures and a pointer that live numbers live in the registry. It stops short of naming the specific sibling tools (e.g. get_tax_rate) an agent should call instead, so it is strong but not fully routable.

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, yet it only states the retrieval action. It says nothing about permission/identity requirements implied by author_npub and operator_npub, nor how a missing or unpublished campaign is reported. 'Retrieve' implies read-only, but that is the extent of the 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 short sentence with no filler and the key qualifier ('published') placed before the resource. It is efficient, though the extreme brevity is closer to under-specification than to crispness.

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

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

An output schema exists, so return values need not be described, and the input schema fully documents parameters. What is missing is the routing information (why this over list_campaigns) and the identity/permission context implied by the required npub parameters, leaving the definition merely adequate for a 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 description coverage is 100%, so all four parameters (including the json/markdown format option) are already documented in the schema. The description adds no syntax, format, or identity-resolution detail beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb ('Retrieve') and resource ('a published pricing campaign'), so the agent knows the operation and object. It does not, however, distinguish this single-campaign fetch from the sibling list_campaigns or publish_campaign, which would require the reader to infer the difference from the names alone.

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

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

There is no explicit when-to-use guidance and no mention of alternatives, despite list_campaigns being an obvious sibling that overlaps in subject matter. The word 'published' faintly implies unpublished drafts are excluded, but this is left for the agent to infer rather than stated.

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

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

No annotations exist, so the description carries the full burden and does so: it discloses that the call never probes relays, that it stays a pure lookup because it sits on the cold-start path, that declared order is preserved and 'nothing is ever dropped', and that the file is a curated guess rather than live state. Those are exactly the behavioral traits an agent could otherwise misinfer.

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 answer and ordering guarantee are front-loaded, and the ranking/curation caveats each earn their place. The middle paragraph about operator cold-start and nsec bootstrap is background rationale that is relevant but longer than strictly needed to call the 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?

With an output schema present, return-shape explanation is unnecessary, and the description covers everything else an agent needs: data source, ranking semantics, the no-probe guarantee, and how the ordering changes over time. Nothing material is missing for a zero-parameter read.

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

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

The tool takes zero parameters, which is the baseline-4 case, and the description correctly implies a parameterless lookup. There is nothing further a parameter discussion could add here.

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 opening sentence names a specific verb and resource ('Return the DPYC Nostr relay set') and adds the ordering guarantee ('best first'), which no sibling provides. An agent can immediately distinguish it from report_relay_failure or resolve_service without opening a schema.

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

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

It states the primary use case precisely (operator cold-start seeding from the Oracle), names the counterpart tool 'report_relay_failure' for correcting the ranking, and explicitly excludes the inverse case: 'Report failures only; successes need no announcement.' That is near-complete when/when-not 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?

With no annotations, the description carries the burden, and it does disclose the return format and provenance (raw markdown, GOVERNANCE.md, dpyc-community repo), which signals a safe, stateless read. It stops short of stating read-only semantics, auth needs, or caching/rate behavior, though for a zero-parameter document fetch those are minor.

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

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

Two sentences, front-loaded with the document identity and followed by the concrete return payload. No filler and nothing repeated from structured fields.

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

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

For a zero-param fetch with an output schema already describing the response shape, the description supplies the essential context: which document and from where. The only gap is that it does not help route between this and the other governance/documentation siblings.

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

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

The tool takes zero parameters, so the baseline is 4; the schema is empty and there is nothing for the description to clarify. No parameter-level ambiguity exists.

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 concrete verb ('Fetch') and a specific resource ('the DPYC Social Contract governance document'), then pins down the artifact (raw markdown of GOVERNANCE.md in dpyc-community). An agent knows exactly what this returns, but nothing distinguishes it from documentation-style siblings like 'about', 'economic_model', or 'how_to_join'.

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 versus the many other documentation/spec tools in the sibling list, and no prerequisites or context for retrieving the governance document. The agent must infer usage entirely.

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 burden and does so well: it discloses that this tool returns no figure, that taxation is per-Authority and ad valorem, and that the real fee is reported at transaction time. This prevents an agent from expecting a numeric rate despite the tool's name, though it says nothing about auth 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?

It is front-loaded with the key fact that no network-wide rate exists, then explains the tool's role and the alternative. Slightly stylized prose ('docent', 'Oracle deliberately quotes none') adds flavor but the core information stays tight for a zero-param 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?

An output schema exists, so return contents needn't be described, and with no parameters and no annotations the description covers everything an agent needs to call it correctly. The only gap is sibling-level differentiation among the other explanatory tools.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The text correctly implies no inputs are needed to get the model explanation.

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 role: it explains how Tollbooth certification taxation works and is explicitly 'a docent' that points to the live source. It also warns the agent that no single rate exists, which corrects the potentially misleading name 'get_tax_rate'. It differentiates from the live-figure path (check_price) but not from model-explaining siblings like economic_model or get_rulebook.

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

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

It gives clear when-to-use (explain the taxation model) and routes the agent to the explicit alternative for a concrete number — query the relevant Authority's check_price for certify_credits. It stops short of stating when this tool should be preferred over the other explainer-style siblings.

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 present, the description carries the full burden and does well: it discloses the exact content of the payload (eight named steps) and its provenance ('fetched live from docs/how-to-add-authority.md in the dpyc-community repo'), which tells the agent the content is current and read-only. It stops short of stating auth requirements or whether the fetch can fail/rate-limit.

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?

Purpose is front-loaded in the first sentence, with supporting detail in the second. The step enumeration is long but each item helps an agent decide whether this guide covers its need, so it earns its space.

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 no-argument guide tool with an output schema, the description is sufficient: it tells the agent what the document contains and where it comes from, so return-format details can safely live in the output schema. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. No parameter text is needed or missing.

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

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

States a specific deliverable: an end-to-end eight-step guide for spinning up a new Tollbooth Authority, plus an itemized preview of what the guide covers. It is clearly a documentation-lookup tool rather than an action tool, but it never names its closest siblings (register_authority, how_to_join) to draw the line explicitly.

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

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

Usage is only implied: an agent can infer this is the pre-flight reading material before calling register_authority, but the description never says when to consult it versus performing the registration itself. No prerequisites, no exclusions, no named alternative.

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 content scope (all five tiers, Nostr keygen instructions, next steps), which implies a read-only informational retrieval. It does not explicitly state that the call is side-effect free, nor mention any authentication or rate-limit behavior, so the safety profile remains inferred rather than declared.

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 sentences, front-loaded with the core purpose before the coverage detail. Minor redundancy in listing tiers and then summarizing contents ('practical next steps'), but nothing wasteful enough to impede selection.

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

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

For a zero-parameter informational tool with an output schema covering the return shape, the description supplies what an agent needs: what the guide is, what tiers it covers, and that it includes keygen instructions. The only omission is how it relates to the register_*/request_citizenship siblings.

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

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

The schema takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. The description correctly implies the tool is parameterless by describing a fixed, tier-spanning guide.

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

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

The description names a specific resource — a tier-specific onboarding guide for joining the DPYC Social Contract — and enumerates its five tiers and contents, so an agent can tell it returns guidance rather than performing a registration. It does not, however, contrast itself with informational siblings such as about, get_rulebook, or economic_model, so sibling differentiation is left to inference.

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: an agent can guess this guide should be read before invoking register_advocate, request_citizenship, or confirm_citizenship, but the description never states that sequencing or names those alternatives. No when-not-to-use or prerequisites are 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 burden and does disclose meaningful behavior: the call is unimplemented, creates a GitHub Issue, imposes a 72-hour discussion period, and uses Lightning-funded economic voting. It omits auth/permission requirements, but the operational disclosure is unusually rich for a stub.

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 sentences with the purpose front-loaded and the implementation caveat immediately after; no filler. Slightly less than ideal only because the second sentence packs multiple mechanics that could be one clean clause.

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

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

An output schema exists, so return values need not be described, and the implementation status is covered. But for a tool with two fully required, undocumented parameters, the description should clarify the npub identifier and reason semantics — a real gap remains.

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

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

Schema coverage is 0% for two required parameters, so the description must compensate and largely fails: 'against a member' loosely implies target_npub identifies a member, but the npub format and the role of 'reason' are never explained. The agent is left guessing at both required inputs.

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 (Initiate) and resource (community ban election against a member), which is enough to distinguish it from siblings like cast_ban_vote and check_ban_status. An agent can tell what this tool does without opening the schema.

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

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

The 'Not yet implemented' warning is a genuinely useful when-not-to-use signal, effectively telling the agent the call will not perform the ban. However, it names no alternatives (e.g., cast_ban_vote) and gives no conditions for legitimate use, leaving routing 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 exist, so the description carries the full behavioral burden. It does disclose the ordering algorithm (live web search frequency for the week, network pick first, curated community order as fallback) and that ranked_by reveals which order was used — genuinely useful non-obvious behavior. It stops short of stating that the data is read-only, cache/freshness implications, or how many wallets are returned.

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

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

Front-loaded with the purpose, then a compact enumeration of returned fields and the ordering rule. Mostly tight, but the trailing fragment 'Free.' and the broken line-wrapping format add little and slightly interrupt the read.

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

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

For a zero-parameter list tool with an output schema, the description goes beyond the minimum by explaining what each item contains and how ordering is determined (including the ranked_by indicator). Nothing an agent needs to select or call this tool is missing.

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

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

Zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The description correctly requires no input from the caller and does not invent spurious 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?

States a concrete resource with scope: Lightning wallets a newcomer can install to pay a Tollbooth invoice, and enumerates what each entry contains (store links, one-line description, custody flag, in-app bitcoin purchase). This is clearly distinguishable from siblings like list_services or resolve_service, which deal with network services rather than wallet recommendations.

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 context is explicit: for someone who needs a wallet to pay a Tollbooth invoice. However, it never names an alternative or a when-not condition (e.g., what to use if the user already has a wallet, or how this relates to list_services/resolve_service). Clear context, 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 behavioral burden. 'List' and 'published campaigns' imply a non-destructive read that excludes unpublished items, which is useful, but there is no mention of permissions, pagination, result limits, or ordering — gaps that matter for a read that could return many rows.

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 sentences, zero filler, and the core scope ('published campaigns from DPYC') is front-loaded before the optional filtering note.

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

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

An output schema exists, so return values need no explanation, and both parameters are fully documented in the schema. What remains thin is the behavioral envelope (pagination, auth) for an unannotated list operation, which keeps this from a 5.

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 both optional filters are documented in the schema with their own descriptions, so the baseline of 3 applies. The description restates the same two filters without adding format or identifier-syntax detail beyond the schema.

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

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

The description names a specific verb+resource ('List published pricing campaigns') and adds scope ('from the DPYC community'), so an agent immediately knows what this returns versus the singular sibling get_campaign. It does not explicitly contrast itself with any sibling, which keeps it 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?

'Optionally filter by operator or author npub' tells the agent the filters exist but not when to use them, when not to, or which sibling to prefer for a single campaign lookup. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and delivers: it discloses per-service timeouts, partial results, brief caching, registry-only fallback when an endpoint is asleep, that nothing is hardcoded, and that it is free and unauthenticated. This is exactly the behavioral context an agent needs before calling.

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

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

Front-loads the core purpose in the first sentence, then layers mechanism, resilience, and access model. Each paragraph is purposeful, though the four-paragraph block is slightly longer than strictly necessary for a two-parameter read 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?

An output schema exists, so return-value detail is unnecessary; the description instead covers the pieces an agent still needs — data provenance, resilience/fallback behavior, auth and cost. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds conceptual depth beyond the schema for probe (lightweight MCP handshake against each member endpoint, no network fan-out when False) and clarifies that kind filters the member roster by role, earning a small bump.

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 (enumerate) and resource (live DPYC service network) with scope (self-described summaries, member roster). An agent can distinguish it from siblings like resolve_service, service_status, and list_campaigns without opening any schema.

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

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

Explains the key usage decision via the probe flag: True for live handshake, False for a fast registry-only listing, and points to the service's check_price for pricing. However, it never names a sibling alternative or states explicit when-not conditions, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the outcome shape ('full member record if found, or a not-found message'), but says nothing about read-only safety, permission/auth requirements, or rate limits, leaving meaningful gaps for an unannotated 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?

Three short sentences, front-loaded with the core action and key parameter, with no filler. Slightly more could be trimmed, 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?

An output schema exists, so return-value detail is not required. The description covers the key parameter meaning, scope of roles, and success/failure outcome, which is sufficient for a simple single-parameter lookup, though auth expectations are unstated.

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

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

The schema has 0% description coverage, so the description must compensate. It adds the key semantic detail that the input is a 'Nostr npub' (format hint), but does not specify validation rules, expected length/prefix, or whether any alias form is accepted.

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+resource ('look up a member') and names the lookup key ('Nostr npub'), which is precise enough for an agent to recognize the retrieval operation. It does not explicitly differentiate itself from siblings like check_ban_status or confirm_citizenship, but the member-record retrieval purpose is unambiguous.

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 clarifies scope ('any role's npub — citizen, operator, or authority'), which implies when the tool applies, but gives no explicit when-to-use vs when-not guidance relative to siblings that also touch member state. Usage 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?

With no annotations, the description carries the full burden. It usefully discloses the data source and freshness ('fetched live from ADVISORY.md in the dpyc-community repo'), but says nothing about permissions, caching, rate limits, or failure behavior when the source is unreachable.

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

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

Three short sentences, front-loaded with the core purpose and then the return content and source. No filler or redundancy.

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

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

An output schema exists, so return values need not be explained, yet the description still summarizes them helpfully. For a simple zero-arg read tool this is essentially complete; only auth/failure context is absent.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter surface to document and the description correctly adds none.

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+resource ('Get current network deployment advisory') and elaborates the content type (changes, urgent upgrades, operator actions). It distinguishes itself reasonably from informational siblings like network_versions and get_rulebook by scope, though it never explicitly contrasts them.

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

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

Usage is only implied – an agent can infer this is the tool for 'what should I do next' guidance, but the description names no alternatives (e.g., network_versions for version data) and gives no when-to-use or when-not-to-use 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 does disclose one useful behavioral trait — the data is fetched live from network-status.json in the dpyc-community repo — which implies a read-only, externally-sourced, potentially volatile response. It omits auth requirements, caching behavior, and failure modes, and its description of return fields is redundant given an output schema exists.

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

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

Three short sentences, front-loaded with the action and scope. The middle sentence enumerating return fields is partly wasted effort because an output schema already exists, but the whole thing stays tight and readable.

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

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

For a zero-parameter read-only tool with an output schema covering the return shape, the description gives enough to call it correctly: scope, source, and liveness. The main gap is the absence of any routing against the close sibling network_advisory.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The empty schema with additionalProperties:false is consistent with the description's claim that it returns all components with no filtering.

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 (Get) and resource (current recommended versions of all Tollbooth components), making the operation unambiguous. It does not, however, distinguish itself from the similarly-named sibling network_advisory, so an agent cannot rule out overlap from the text alone.

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. The description never says when an agent should call this versus network_advisory, about, or economic_model, nor does it state any prerequisite or trigger condition. Usage is left entirely to inference from the tool 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 adds meaningful context: it commits both JSON and Markdown artifacts, requires NIP-98 signing with author_npub, and enforces publication under the author's own name. It does not disclose overwrite/conflict behavior or validation failure modes, but the core side effects and authentication requirement are clear.

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 three tight sentences, front-loading the core action, then side effects, then the authentication constraint. Every sentence adds useful information with no filler.

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

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

For a mutation tool with no annotations and an output schema, the description provides the essential behavioral context: artifact creation, signed-request requirement, and author identity enforcement. It could be more complete by noting overwrite behavior or validation expectations, but return values are covered by the output schema.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description reinforces that author_npub is used for signing and that campaign_markdown may be generated, but it does not add substantial semantics beyond the schema's own parameter descriptions.

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 and resource ('Publish a pricing campaign') and names the target community, clearly distinguishing it from read-oriented siblings like get_campaign and list_campaigns. An agent can identify the operation without opening the schema.

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

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

The description implies when to use the tool by describing publication, but it does not explicitly contrast it with siblings such as list_campaigns or get_campaign, nor does it state when not to use it. The signing requirement is a constraint, not usage 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?

With no annotations, the description carries the full behavioral burden and does disclose the key constraint: the request must be NIP-98 signed with the npub's own key, so only the holder can register that npub. It omits other traits an agent would want -- idempotency, what happens on duplicate registration, or error behavior -- but the auth disclosure is a genuinely valuable addition.

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

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

Front-loaded with the core action, followed by two tight paragraphs on what an Advocate is and the signing requirement. Every sentence earns its place; the definitional middle paragraph is slightly longer than strictly needed but still functional.

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

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

An output schema exists, so return values need not be explained, and the description covers the auth prerequisite plus the conceptual scope of the resource. What remains thin is failure/duplicate handling and the concrete distinction from register_operator in instruction terms, but the definition is broadly complete for calling it correctly.

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

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

Schema description coverage is 100%, so each of the five parameters is already documented in the schema, including the npub and service identifiers. The description adds only that npub must correspond to the signing key, which is auth semantics rather than parameter syntax, so the baseline 3 applies.

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

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

States a specific verb and resource ('Register a new Advocate in the DPYC community registry') and then defines what an Advocate is, explicitly distinguishing it from monetized Operators and certification Authorities -- both of which are siblings (register_operator, register_authority). An agent can route correctly without opening any schema.

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

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

The definition of an Advocate versus Operators/Authorities implicitly tells the agent when this tool applies, and it states the self-registration precondition clearly. It never names a sibling as the alternative or states a negative condition (e.g., 'do not use for monetized services'), so it falls short of explicit when/when-not routing.

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 the write side effect (committing a file to GitHub) and the approval/ownership preconditions. It stops short of stating auth requirements, idempotency behavior for an already-registered npub, or failure modes, which would matter for a mutation 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?

Front-loaded with the core action, then the protocol context. The three-step enumeration is somewhat verbose but each line maps to a real sibling tool and genuinely disambiguates ordering, so it earns its space.

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

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

An output schema exists, so return values need no explanation, and the description covers preconditions and side effects well. Missing only operational details like auth requirements and duplicate-registration handling, which is a minor gap for a four-param mutation tool.

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

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

Schema coverage is 100%, so all four parameters are already documented in the schema, including the 'must already exist as a prime_authority or authority' constraint on upstream_authority_npub. The description adds no format or validation detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Register a new Authority in the DPYC community registry') and pins down the concrete side effect ('Commits a new members/authorities/{npub}.json file to dpyc-community on GitHub'). This clearly separates it from siblings like register_operator and register_advocate.

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

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

Explicitly states the calling context (called by an Authority service at the end of the onboarding protocol) and the precondition (candidate proved npub ownership, Prime Authority approved). It also names the two preceding steps register_authority_npub and confirm_authority_claim, so an agent knows this is the terminal step rather than the entry point.

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 a real behavioral prerequisite – the request must be signed with the Authority's key – but says nothing about duplicate-registration behavior, idempotency, or what the registry does on failure.

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 sentences, no filler, with the core action front-loaded and the precondition immediately after. Every sentence earns its place.

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

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

An output schema exists, so return values need no explanation, and the schema fully documents the inputs. The description covers the trigger and the signing requirement, but for an unannotated mutation tool it leaves edge cases such as re-registration 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 100%, so all four parameters are already documented in the schema, including the constraint that authority_npub must already exist as an authority or prime_authority. The description adds only the signing requirement, which loosely maps to authority_npub, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Register a new Operator') plus the scope ('in the DPYC community registry'), which cleanly separates it from siblings like register_authority, register_advocate, and update_operator. An agent can select this tool without opening the schema.

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

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

Explicitly names the caller and the trigger condition: an Authority service acting after its owner approves an adoption request. It does not name alternative tools (deregister_operator, update_operator) or state when not to use it, so it falls short of full routing guidance.

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

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

With no annotations, the description carries the full burden, and it delivers the single most important behavioral fact: the tool is not yet implemented and will open a GitHub PR against the registry. That is exactly the kind of context an agent needs. It still omits auth requirements, whether the caller must own the npub, and reversibility, so it is not a 5.

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

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

Two short sentences, front-loaded with the purpose before the implementation caveat. Every clause carries information, though the em-dash split between 'not implemented' and the PR mechanism reads slightly awkwardly.

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

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

An output schema exists, so return values need not be explained, and the not-implemented status is disclosed. However, for a mutation-style tool with zero annotation coverage, the description leaves authorization and identity-binding questions open, which matters for a registry-changing operation.

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

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

Schema description coverage is 0% for the single required parameter 'npub', and the description never mentions the parameter, its expected format (Nostr public key), or whether it must match the caller's own identity. The word 'member' only loosely gestures at it, leaving the parameter effectively undocumented.

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 ('Citizen self-removal from the DPYC Social Contract') and the mechanism (automated PR), which is clear enough to separate it from operator-side tools like deregister_operator. It does not explicitly name a sibling to route against, so it stops short of a 5.

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

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

The phrase 'Citizen self-removal' implies the use case (a member leaving voluntarily), but there is no statement of prerequisites, no named alternative (e.g., how this differs from deregister_operator or confirm_citizenship), and no exclusions. Usage must be inferred.

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 load and does well: it discloses the side effect (triggers an Oracle probe), the non-effect (does not set rank, cannot be used to demote a healthy relay), abuse resistance ('costs one probe and changes nothing'), and the stateless no-challenge design. It does not discuss rate limits on repeated reports or what happens on a failed probe.

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?

Purpose is front-loaded in the first line, and the rest elaborates usefully. Mild redundancy: 'no caller can demote a healthy relay by asserting that it is down' restates 'A report does not set a relay's rank,' costing a clause without new information.

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

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

An output schema exists, so return values need not be explained, and the description covers intent, effect, non-effect, and the stateless signing model. Missing only secondary operational details such as what happens if the relay is out of the DPYC set or how repeated reports are handled.

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 reinforces the 'relay must be in the DPYC set' constraint and the failure-only intent behind `mode`, but adds no syntax, format, or validation detail 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?

Specific verb and resource ('Report that a relay in the DPYC set was unreachable'), plus the secondary effect (re-rank). The scoping clause ('must already be in the DPYC set... not a probe-anything primitive') cleanly separates it from siblings like get_relays, service_status, or resolve_service.

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

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

Gives explicit when-not guidance: 'Report only failures. Successes are far too frequent to be worth carrying.' It also frames the expected outcome (a probe, not a rank change). It stops short of naming an alternative tool for the read/check side, so routing is strong but not exhaustive.

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 so well: it discloses the cryptographic challenge step, that the nsec never leaves the applicant's device, the required follow-up call (confirm_citizenship), and a 10-minute expiry window. These are exactly the behavioral traits an agent needs to sequence the flow correctly.

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

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

Front-loaded with the core distinction and flow, with no truly wasted sentences. It is somewhat long and repeats the 'registration path' idea across paragraphs, but each block adds routing or sequencing value.

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

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

An output schema exists, so return values (challenge_id, nonce, signing instructions) need not be re-explained, and the description still summarizes them. The challenge-sign-confirm sequence and its time limit make the definition complete 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 0%, so the description must compensate. It adds real meaning for npub (it becomes the patron identity keypair used for credit purchases and service access), but display_name is never explained. Partial compensation for a two-parameter tool.

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 ('Begin the citizen registration process') and explicitly distinguishes this citizen path from the operator path that goes through the Authority. An agent can tell it apart from register_operator and register_authority without opening any schema.

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

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

Specifies who calls it (the Operator on behalf of a patron), that it invokes the Oracle directly, and that no Authority npub is required or consulted. It also names the alternative flow explicitly ('Not to be confused with operator registration, which goes through the Authority via a Nostr DM delegation request').

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 the derived source (the operator's upstream_authority_npub) and the read-only nature implicitly, but says nothing about failure modes (e.g., operator with no upstream authority), permissions, or lookup cost.

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

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

Front-loaded with the action and resource, then the return shape, then the usage note. Three compact sentences with essentially no filler, though the return-shape detail partially duplicates the 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?

An output schema exists, so return values are already machine-described, yet the description still summarizes the {npub, url, name} payload helpfully. For a single-parameter read tool this is nearly complete; only error/no-authority behavior is 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 0% — the single parameter is a bare "npub" with no description. The text compensates by clarifying it is an operator npub ("Resolve the certifying Authority for an operator npub"), but adds no format, validation, or edge-case guidance beyond that.

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 (resolve) and a specific resource (the certifying Authority for an operator npub), plus what it returns. It is clearly distinguishable from siblings like register_authority, how_to_add_authority, and update_operator.

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

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

"Use this after bootstrap to learn — and verify — which Authority signed your config" gives a concrete when-to-use condition and an alternative it replaces (reading GitHub). It stops short of explicit when-not-to-use or naming a sibling as an alternative.

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 the return shape and clarifies that purchase_mode is a topology fact rather than a price, but says nothing about read-only nature, auth requirements, or error behavior when neither/both keys are supplied.

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

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

Three tight sentences with the purpose front-loaded, followed by output facts and then the selection constraint. Slightly dense markup but no wasted prose.

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

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

An output schema exists, so return values needn't be fully enumerated, yet the description still explains the ambiguous purchase_mode field. For a simple two-parameter lookup the coverage is nearly complete, with only read-only/auth context missing given zero annotations.

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

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

Schema coverage is 0% and both parameters are optional with empty-string defaults, so the description compensates meaningfully by stating that exactly one of name or npub must be supplied. It doesn't add format details (e.g. npub encoding) beyond that.

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 (resolve) and resource (DPYC service) plus the two lookup keys, which is enough to distinguish it from list_services and resolve_authority_for. It is clear but does not explicitly contrast itself against 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?

It gives an invocation constraint ('Supply exactly one of name or npub') but never says when to reach for this tool versus list_services or resolve_authority_for, nor any prerequisites. Usage is implied rather than directed.

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 supplied the description carries the full load, and it delivers the two facts an agent most needs: the call is free and unauthenticated. It does not mention rate limits, caching, or freshness of the reported runtime info, which keeps it 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?

Two sentences, no waste, and the identification of the tool is front-loaded ahead of the cost/auth note and the usage hint. Every clause earns its place.

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

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

An output schema exists so return values need no explanation, and there are no parameters to document; purpose, cost, and auth are all covered. The only missing piece is sibling differentiation against network_versions.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly says nothing about inputs rather than padding.

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: 'report this service's software versions and runtime info.' The scope word 'this service's' implies a single-node diagnostic, but sibling 'network_versions' is never named, so the boundary between the two is left for the agent to infer.

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

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

'Use to verify deployment versions across the DPYC ecosystem' gives a concrete when-to-use, which is more than most. However, it offers no exclusions and never distinguishes itself from the sibling network_versions, which sounds like an overlapping version-reporting 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 the approval workflow (owner approves) and the authorization requirement ('the request must be signed with that Authority's key'). It omits failure behavior and whether unlisted fields are preserved, though the schema covers the latter.

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

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

Three short sentences, front-loaded with the action, then when-to-use, then the authorization constraint. No filler and nothing buried.

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?

Output schema exists so return values need not be explained. Purpose, trigger conditions, and the signing/approval requirement are all present, which is everything an agent needs to invoke this mutation correctly.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including 'leave empty to keep current'. The description's mention of endpoint and display-name changes loosely maps to those fields but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: 'Update an existing Operator's registry entry.' The word 'existing' implicitly separates it from register_operator and deregister_operator, but it never names those siblings directly. An agent can still tell what it does at a glance.

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

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

Gives clear trigger scenarios ('moves to a new MCP endpoint, changes its display name, or needs to correct a registration') and states the calling context. It does not explicitly exclude alternatives like register_operator/deregister_operator, so it stops short of full routing guidance.

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

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

No annotations are supplied, so the description carries the burden, and it does disclose the returned fields (npub, display name, member record) and implies a read-only lookup via 'Identify'/'Returns'. It stops short of stating auth requirements or whether this is chain-state dependent, leaving a modest 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?

Two short sentences with the purpose front-loaded and the return shape following. Every clause earns its place with no filler.

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

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

For a zero-parameter read tool with an output schema already present, the description covers the essential what and returns. The only meaningful omission is routing guidance against similarly-named sibling lookups, which keeps it from a 5.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing parameter-wise for the description to clarify beyond what the empty schema already conveys.

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 ('Identify') and resource ('the First Curator (Prime Authority) of the Certification Chain'), so the intent is unambiguous. It does not, however, differentiate itself from adjacent siblings like resolve_authority_for or lookup_member, which an agent might reasonably confuse with this lookup.

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

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

The description says what the tool does but gives no when-to-use condition, no prerequisites, and no mention of alternatives such as resolve_authority_for. The agent must infer the trigger scenario entirely.

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