dpyc-oracle

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 that the tool fetches external files from a repository and assembles a response, which is useful behavioral context. However, it omits details like whether it makes network calls, whether it caches results, or any error conditions. For a simple read-only tool, this is adequate but not rich.

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 two sentences with zero wasted words. It front-loads the purpose ('Extended narration') and then provides concrete details about the fetched files and output. This is a model of conciseness.

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

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

Given the tool's simplicity (no parameters, no annotations) and presence of an output schema, the description provides sufficient context: it explains what the tool does, its data sources, and its output type. It could slightly improve by mentioning whether it returns raw file contents or a synthesized answer, but the phrase 'assembles a comprehensive context answer' largely covers that.

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 has zero parameters, so the description does not need to elaborate on parameter semantics. The schema is empty and fully covered, and a zero-parameter tool gets a baseline of 4. The description adds no confusion and correctly leaves out parameter details.

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

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

The description uses a specific verb ('Fetches') and resource ('README.md and GOVERNANCE.md from the dpyc-community repo') to clearly state what the tool does. It also names the content domain ('DPYC, the Social Contract, and the Oracle'), which distinguishes it from sibling tools like get_rulebook or how_to_join that focus on specific topics.

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 usage for general questions about DPYC and its governance by mentioning it assembles a 'comprehensive context answer,' but it does not explicitly state when to use this tool versus alternatives. No exclusions or references to sibling tools are provided, so the guidance is only implied.

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

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

The description explicitly states 'Not yet implemented', which is a critical behavioral disclosure beyond the schema. It also outlines the intended behavior (verify membership, validate election, record vote with Lightning payment proof). It does not detail failure modes or side effects of a non-implemented tool, but the main caveat is clearly communicated.

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 two sentences: the first clearly states the purpose, the second provides status and key behavioral steps. No wasted words, information is front-loaded, and the 'Not yet implemented' warning is included without bloat.

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?

The tool has 3 required parameters with no schema descriptions, and while an output schema likely exists, the description does not address return values or error behavior. It covers the main purpose and the not-implemented status, but for an agent to invoke correctly it needs more detail on vote format and possible outcomes. The lack of documentation for a non-implemented tool is a notable gap.

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?

With 0% schema description coverage, the description must compensate for parameter meaning. It references npub ('verify npub membership'), election_id ('validate the election is active'), and vote ('record the vote'). However, it does not explain expected formats or allowed values (e.g., what the vote string should be), leaving important semantic gaps.

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

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

The description starts with a specific verb and resource: 'Cast a Lightning-funded vote in an active ban election.' It clearly distinguishes from sibling tools like initiate_ban_election (which starts an election) and check_ban_status (which checks status). The action is unambiguous and the resource is well-defined.

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

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

The description provides clear context for when to use the tool: it must be an active ban election, and it mentions verifying npub membership and election validity. It does not explicitly name alternatives or give when-not-to-use guidance, but the context is clear enough that an agent can infer appropriate usage.

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

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

With no annotations, the description carries the full burden. It discloses a key behavior: 'Unknown npubs are not considered banned (they simply aren't members).' Also states 'Free, unauthenticated,' which is useful for understanding access. The read-only nature is implied by 'Check whether.' While side effects are not explicitly denied, the description provides sufficient behavioral context for a simple lookup.

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/paragraphs, each adding value. The main purpose is first, followed by nuance and usage context. No redundancy or 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 tool with one param and an output schema, the description covers the operation, the not-found case, auth requirements, and typical usage. It does not describe rate limits or data freshness, but these are not critical for this simple check. The output schema exists, so return-value details are not needed here.

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 only one parameter 'npub' with no description (0% coverage). The description mentions the parameter in the tool's purpose and states 'Looks up the member in the community registry,' which explains its use. However, it does not specify format, valid values, or edge cases beyond the unknown-npub behavior, which is more behavioral than parameter semantics. Thus minimal additional meaning.

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

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

The description opens with a specific verb and resource: 'Check whether an npub is banned from the DPYC Social Contract.' This clearly distinguishes it from sibling tools like cast_ban_vote (which votes on bans) and lookup_member (which retrieves member details).

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 provides explicit context: 'Used by operators during the cold path (credit purchases) to enforce community bans.' and states 'Free, unauthenticated.' It does not explicitly mention alternatives, but the intended use case is clear.

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 provided, the description takes full responsibility for behavioral disclosure. It lists five verification steps (challenge validity, Schnorr signature, pubkey match, nonce content, npub uniqueness) and clearly states the side effect: 'commits directly to dpyc-community/members/citizens/{npub}.json'. This is highly transparent about the tool's write behavior and failure conditions.

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

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

The description is well-structured and front-loaded with the primary action. It then provides context, a numbered verification list, and the success outcome. Every sentence adds value and there is no redundant wording. The format is easy to parse for an AI agent.

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?

Given the tool's complexity (3 required parameters, no annotations), the description is remarkably complete. It covers the entire flow, preconditions, verification checks, and the exact commit behavior. Since an output schema exists, the lack of a return value description is not a gap. The tool is fully self-contained for an agent to select and invoke correctly.

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

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

The input schema has no descriptions (0% coverage), so the description must compensate. It does so by explaining the context: the challenge, the signed event, and the claimed npub. The verification steps mention 'challenge exists', 'Schnorr signature', 'pubkey matches claimed npub', and 'event content contains the issued nonce', which implicitly define the three parameters. However, there is no explicit per-parameter mapping (e.g., 'challenge_id is the ID returned by request_citizenship'), so it falls just short of a perfect score.

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

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

The description clearly states the tool's purpose: 'Complete the citizen registration by submitting a signed Nostr event.' It specifies the exact action (confirming citizenship), the resource (citizen registration), and distinguishes itself from sibling tools like request_citizenship by positioning it as the second step in the flow. The verb 'complete' and the mention of 'citizen registration flow' make it 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?

The description explicitly states when this tool should be used: 'The Operator calls this on behalf of a patron after the patron has signed the cryptographic challenge from request_citizenship.' It conveys a clear precondition and caller role, effectively telling the agent not to use it before request_citizenship or without signed challenges. This is explicit contextual 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 provided, the description carries the full burden of behavioral disclosure. It clearly discloses the destructive nature: 'deregistration removes the member file entirely, returning the Operator to initial state.' This goes beyond simply saying 'deregister' and informs the agent that the operation eliminates the member record and resets state.

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 concise and well-structured: a clear first sentence states the action, followed by the trigger context and the consequence. Every sentence contributes useful information with 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?

For a two-parameter destructive tool with a complete input schema and an output schema present, the description covers the trigger condition, the action, and the resulting state. It could add an explicit irreversibility warning, but 'removes the member file entirely' already conveys the significant consequence.

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 parameters already have meaningful descriptions in the schema. The tool description does not add parameter-level semantics beyond what the schema provides, so the baseline score 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?

Description uses a specific verb ('Remove') and resource ('Operator from the DPYC community registry'), and further clarifies that deregistration removes the member file entirely. The trigger context ('Called when an Authority disowns an Operator') makes the purpose unambiguous and distinguishes it from related tools like register_operator or 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?

The description explicitly states the condition for use: 'Called when an Authority disowns an Operator.' This gives clear context for when the tool is appropriate, though it does not name alternative tools or explicitly state when not to use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool provides qualitative explanation only, avoids all quantitative figures, and is 'Free, unauthenticated.' It also indicates the tool is a 'docent' rather than a live data source, which is valuable behavioral context.

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 exceptionally concise: three sentences that front-load the purpose, then add critical boundary information (no quantitative data, free/unauthenticated). Every sentence earns its place with no filler or repetition.

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

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

For a no-parameter, qualitative explanation tool with an output schema, the description covers the essential aspects: what the tool explains (value flows, certification fees, cascade, first curator), where live data lives, and what it deliberately does not cover. This is complete for the tool's intended use.

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 schema provides no parameter information. The baseline for no-parameter tools is 4. The description appropriately focuses on content and behavior rather than parameters, which is sufficient given the absence of 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?

The description opens with a specific verb and resource: 'Explain the DPYC Social Contract economic model — qualitatively.' It clearly identifies the tool's function and distinguishes it from quantitative tools like get_tax_rate by emphasizing the qualitative nature and stating that it provides no rates or figures.

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 explicitly states when NOT to use this tool: 'The Oracle quotes no rates, counts, or revenue figures — those belong to the Authorities' pricing models and the live registry, not to a docent.' This clearly redirects users to alternative sources for quantitative data, providing strong 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 provided, the description carries full responsibility for behavioral disclosure. It only says 'Retrieve...' which implies a read operation, but it doesn't state what happens for missing or unpublished campaigns, whether any targeting is needed, or that the 'format' parameter changes the output shape. The 'published' qualifier adds a minor constraint but little else.

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

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

One short sentence with no filler. The verb and target are front-loaded, and every word 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?

For a simple retrieval tool with a complete schema and an output schema, this is minimally viable. However, it lacks guidance about the 'format' parameter's effect, the selection criteria between get_campaign and list_campaigns, and what happens if the campaign isn't published or doesn't exist. The outpu schema covers return values, but the description is thin on operational context.

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 input schema already documents all four parameters and their meanings. The description itself adds no parameter-level detail, so it stays at the baseline 3.

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 ('Retrieve') and resource ('published pricing campaign'), clearly distinguishing it as a singular-item getter against siblings like list_campaigns and publish_campaign. It doesn't explicitly name or contrast those siblings, 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?

There is no guidance on when to use this tool instead of list_campaigns, how to obtain the required npub/slug values, or any exclusions for unpublished campaigns. The word 'published' implies a constraint but the description never says 'use this over X' or 'not for unpublished.'

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

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

Annotations are absent, so the description carries the full burden manfully: it discloses the call performs no probing, the data is a curated guess not a live status, unreachable relays get moved to the back, and it only reads from a fixed source. It also mentions the cost ('Free'). The only minor gap is no explicit note that it has no side effects or auth requirements, but the description's statements imply it's a pure read.

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 fairly long for a zero-parameter tool, but it front-loads the core purpose (first sentence) and each subsequent sentence adds meaningful behavioral context (source of truth, no probing, price, feedback loop). It could be trimmed but it's not padded with fluff.

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 lookup tool with no parameters, the description fully explains what the result is (ordered relay set), how it's maintained (single source of truth, moved on reports), why it exists (cold-start seeding), and what it does NOT do (probe or guarantee current status). It even ties to the sibling report_relay_failure. Nothing critical is missing.

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

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

No parameters exist (0 params, schema coverage 100% trivially), so the baseline is 4. The description adds nothing about parameters because there are none, which is appropriate.

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

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

The description states a specific verb and resource: 'Return the DPYC Nostr relay set, best first.' It clearly distinguishes what the tool does (returns a relay set) and its ordering, and mentions the source of truth. It also differentiates from report_relay_failure by explaining it's a lookup, not a report. This is unambiguous and separates it from sibling tools.

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

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

Explicitly positions the tool on the operator cold-start path ('its only fixed dependency is this Oracle endpoint'), says it 'stays a lookup', and tells the agent to use report_relay_failure for reporting dead relays ('Report failures only'). This makes the when/why and the alternative clear.

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 provided, the description carries the full burden of behavioral disclosure. It provides two important behavioral details: the return format ('raw markdown') and the source ('dpyc-community repo'). This goes beyond a generic 'fetch' and informs the agent about output type and repository origin, though it does not mention error handling or authentication.

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 extremely concise, consisting of two short sentences. The main function is front-loaded in the first sentence, and the second sentence adds necessary return-format detail. No filler or redundant information is present.

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 tool that simply fetches a static document, the description is quite complete: it names the document, the repository, and the return format. The presence of an output schema further reduces the need for describing return structure. However, it does not mention potential error cases or versioning, which could be useful but are not critical for such a simple 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?

The tool has zero parameters, so the baseline is 4. The description adds meaning by specifying what is being fetched (the governance document) and the exact file, which is useful context even though there are no parameters to describe.

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

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

The description clearly states the tool's function with a specific verb ('Fetch') and a specific resource ('the DPYC Social Contract governance document'). It also uniquely identifies the exact file (GOVERNANCE.md) and repository, distinguishing it from all sibling tools which handle operations, registrations, or other data.

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

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

The description implies usage by naming the exact document to fetch, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or alternative tools. Since no sibling tool appears to fetch governance docs, the usage context is somewhat self-evident, but explicit guidance is missing.

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 full behavioral disclosure. It reveals the tool is a 'docent' that explains the model and points to a live source, but deliberately does NOT return a tax rate. It also notes the actual fee is reported at transaction time. This is transparent about the tool's non-numeric, informational behavior.

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

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

The description is four sentences, tightly packed with essential information. It front-loads the main purpose, explains the key conceptual point (per-Authority, no network-wide number), states what the tool does, and gives the alternative. No wasted words.

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?

Given the tool's simplicity (no parameters), the presence of an output schema, and the explanation of the model and alternatives, the description is complete. It covers what the tool does, what it doesn't do, and where to get exact data. The output schema handles return structure details.

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 has zero parameters, so the baseline is 4. The description does not need to add parameter semantics since there are none. It clearly frames the tool as a conceptual explainer, which is sufficient for a parameterless 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?

The description clearly states the tool's purpose: 'Explain how Tollbooth certification taxation works.' It uses a specific verb ('Explain') and resource ('Tollbooth certification taxation'), and explicitly distinguishes itself from returning a numeric rate, which differentiates it from any hypothetical rate-returning sibling.

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

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

The description provides explicit usage guidance: it tells the agent when to use this tool (to understand the taxation model) and when not to (for exact figures). It names the alternative: 'query the relevant Authority's check_price for certify_credits.' This is a clear when/when-not distinction with an alternative 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. It discloses that it fetches live from a docs file and returns a specific list of steps, which is transparent. It does not explicitly state the operation is read-only, but that is strongly implied by it being a guide.

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 concise and front-loaded, stating the purpose in the first sentence. It then efficiently enumerates the covered content and the source. 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?

Given the tool is a simple guide with no parameters and an output schema, the description provides sufficient context: what it does, what it returns, and where it is fetched from. It is complete for its purpose.

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 has zero parameters, so the baseline is 4. The description correctly focuses on the return value rather than parameter details, and no further parameter explanation is needed.

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

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

The description clearly identifies the tool as an end-to-end guide for setting up a new Tollbooth Authority, with a specific verb ('guide') and resource ('Tollbooth Authority'). It differentiates from sibling tools like register_authority by clarifying it returns a procedure rather than performing the action.

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

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

The description gives clear context that this is a guide, implying it should be used when instructions are needed rather than to perform registration. However, it does not explicitly state when not to use it or name alternatives, so it falls short of a 5.

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 correctly conveys that this is a content-only guide with no side effects, but it does not explicitly state that the tool is read-only or that it makes no state changes. The informational tone is adequate but lacks an explicit safety guarantee.

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 two sentences, front-loaded with the core purpose, and every word adds value. It efficiently lists all covered tiers and highlights key specifics like Nostr keygen, 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?

Given the tool's simplicity (zero parameters, output schema present) and the rich content in the description, it is fully complete for an agent to understand the tool's scope. It covers the audience (tier-specific), content (onboarding guide, keygen, next steps), and distinguishes from related action 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 has zero parameters, so the description does not need to explain parameter semantics. The empty input schema is fully self-descriptive, and the baseline of 4 applies as no compensation is necessary.

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

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

The description clearly identifies the tool as an onboarding guide for joining the DPYC Social Contract, with specific coverage of five tiers and practical steps. It distinguishes itself from sibling registration tools by being the informational resource rather than the action, but lacks a direct verb like 'get' or 'view'.

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 explicit guidance on when to use this tool versus alternatives. While the name and description imply it is for newcomers, it does not state that users should consult this before using registration tools like request_citizenship or register_authority, and no exclusions or alternative references are provided.

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 full burden. It discloses planned behavior (creating a GitHub Issue with a 72-hour period and voting) but does not specify what the tool actually does today when invoked, such as returning an error or being a no-op. This lack of clarity about current behavior is a significant 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?

The description is two clear sentences, front-loaded with the purpose and followed by a concise caveat. Every sentence delivers essential information with no redundancy or 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?

Given the tool is marked 'Not yet implemented,' the description should clarify behavior on invocation and any limitations. It also lacks details about the output schema (which exists but is not described) and how the voting mechanism works. The current content leaves critical gaps for an agent deciding whether to call it.

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 the description does not explicitly explain the parameters. The phrase 'against a member' hints at target_npub and 'reason' is self-explanatory, but the description adds minimal value beyond the parameter names, leaving ambiguous details like reason format or constraints.

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

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

The description clearly states the action ('Initiate a community ban election') and the target ('against a member'), using a specific verb and resource. It distinguishes from sibling tools like cast_ban_vote and check_ban_status by focusing on the initiation step.

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

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

The description gives implied usage context (used to start a ban election) but provides no explicit when-to-use or when-not-to-use guidance. The 'Not yet implemented' warning serves as a caveat but does not suggest alternatives or explain how to proceed, so guidance is minimal.

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 disclosure burden. It signals a read-only listing operation and explicitly discloses that only published campaigns are returned and that filters are optional. It does not mention ordering, pagination, or auth requirements, but the presence of an output schema covers the return contract. This is adequate for a simple list tool.

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

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

Two sentences with zero filler; the core action and scope are front-loaded, and the optional filter clause follows naturally. Every word adds value and there is no redundant elaboration.

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

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

For a zero-required-parameter list tool with a full input schema and an output schema, the description is essentially sufficient for correct invocation. It could be improved by explicit pointer to get_campaign for single-campaign lookups, but that is a minor gap. Overall, the definition is complete enough for safe and correct use.

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 fully documents author_npub and operator_npub. The description largely restates these optional filters without adding new semantic detail. Baseline 3 is appropriate because the description does not compensate for or add 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?

The description opens with a specific verb-resource pairing: 'List published pricing campaigns from the DPYC community.' This clearly distinguishes the tool from get_campaign, which targets a single campaign, and publish_campaign, which creates one. The 'published' qualifier further narrows the scope.

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 identifies a clear use case—listing campaigns with optional filters—but it does not explicitly state when to prefer this over get_campaign or how it relates to publish_campaign/list_services. That routing is left to inference from sibling names and context. The usage is implied rather than explicit, so it falls short of a full alternative-routing guide.

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 provided, the description carries the full behavioral disclosure burden and does so thoroughly. It reveals that probing performs a network handshake, that results are partial and cached, that there is a registry-only fallback for unreachable endpoints, and that the operation is free and unauthenticated.

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 organized and efficient: a one-line summary, then mechanism, resilience behavior, and cost/auth status. Every sentence adds useful information, and the most decision-relevant facts are front-loaded.

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?

Given an output schema, low parameter count, and full schema coverage, the description is complete. It explains the discovery mechanism, self-description source, pricing behavior, failure resilience, caching, and access requirements, leaving no practical gap for an agent selecting or invoking the tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds meaning beyond that by explaining the behavioral difference between probe=True and probe=False, including the fast registry-only fallback, which helps an agent choose correctly.

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

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

The description opens with a specific verb and resource: 'Enumerate the live DPYC service network with self-described summaries.' It clearly distinguishes this from sibling tools like lookup_member or resolve_service by describing a network-wide, probe-based listing rather than a single-service 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 clearly establishes the tool's context and includes actionable guidance for the probe parameter, such as 'Set False for a fast registry-only listing (no network fan-out).' However, it does not explicitly mention alternative sibling tools or state when not to use this tool, so it falls short of full exclusionary 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. It discloses the return behavior explicitly: 'Returns the full member record if found, or a not-found message.' This covers both success and failure paths. It does not mention side effects or auth, but as a lookup, the read-only nature is implied.

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 sentences, each adding essential information: the main action, the scope of roles, and the return behavior. It is front-loaded with the core purpose and has no redundant or filler text.

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

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

For a simple lookup tool with one parameter and an output schema (though not shown), the description covers the necessary context: what the tool does, what input it takes, and what kind of output to expect. It is sufficiently complete for the agent to select and invoke 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?

The schema only lists 'npub' as a required string with 0% coverage. The description adds meaning by identifying it as a 'Nostr npub' and specifying that any role's npub is accepted. This helps the agent understand the expected format and scope, compensating for the bare 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 clearly states the tool's function: 'Look up a member by their Nostr npub.' It specifies the verb (look up), the resource (member), and the parameter (npub). It also adds scope by noting it can look up any role's npub (citizen, operator, or authority), which distinguishes it from role-specific sibling tools.

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

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

The description implies usage context: this is the general lookup tool for members across all roles. It states 'Can look up any role's npub,' which tells the user when this tool is applicable. It does not explicitly name alternatives, but given that sibling tools are role-specific operations (e.g., register, confirm), the guidance is clear enough.

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 transparency burden. It discloses that the data is fetched live from ADVISORY.md in the dpyc-community repo, indicating a network fetch and external dependency. It does not mention failure modes or safety, but for a read-only tool this is acceptable.

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 two sentences, front-loaded with the main purpose ('Get current network deployment advisory') followed by the return value and source. 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 parameterless read tool with an output schema, the description fully covers what the tool does, what it returns, and where the data comes from. Complete given its simplicity.

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 has zero parameters, so the schema fully covers the input surface. No parameter explanation is needed, and the baseline of 4 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 opens with a clear verb-object pair ('Get current network deployment advisory') and expands with what it returns (human-readable guidance on changes, upgrades, actions). This distinguishes it from sibling informational tools like network_versions or service_status.

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 use when operators need current advisory info on recent changes and upgrades. It provides clear context but does not explicitly name alternatives or exclusion criteria, though no ambiguity is present.

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

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

With no annotations, the description carries the full burden. It discloses that data is fetched live from a specific source (network-status.json) and describes the return contents, which are non-mutating and read-only. It does not mention error handling or rate limits, but the core 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?

Three sentences, each earning its place: the first states purpose, the second describes the return payload, and the third explains the data source. No wasted words.

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?

Given the tool's simplicity and the presence of an output schema, the description is complete. It clearly explains what is returned, where data comes from, and it is sufficiently detailed for an agent to invoke 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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter information, but none is needed since the schema already confirms no parameters exist.

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 explicitly states the action ('Get') and the resource ('current recommended versions of all Tollbooth components'), clearly distinguishing it from sibling tools that deal with status, advisory, or other information.

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 usage by stating what the tool does and that data is fetched live, but it does not explicitly mention when to use this tool over alternatives, nor does it provide exclusions or alternative tool names.

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 behavioral burden. It does disclose meaningful behavior: it commits both a machine-importable JSON file and a human-readable Markdown summary to the dpyc-community campaigns directory. However, it does not disclose whether re-publishing overwrites an existing campaign, whether the action is reversible, or what permissions are required.

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 two sentences with no filler. The primary action is front-loaded, and the second sentence adds concrete artifact and target-directory information that 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?

Given the output schema and fully documented parameters, the description is close to complete for basic invocation. It still lacks side-effect semantics (overwrite behavior, idempotency) and usage prerequisites, which matter for a publishing 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?

Schema description coverage is 100%, so the schema already documents all five parameters. The tool description adds only the general framing that campaign_json becomes a committed JSON file and campaign_markdown becomes the Markdown summary. This is mildly helpful but not necessary for parameter understanding.

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

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

The description opens with a clear, specific verb and resource: 'Publish a pricing campaign to the DPYC community.' It then explains the exact mechanism, committing both a JSON file and a Markdown summary, which distinguishes this write operation from sibling read tools like get_campaign and list_campaigns.

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

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

Usage is implied rather than explicit: an agent can infer this tool is for publishing campaigns, but the description does not state when to prefer it over alternatives, mention prerequisites, or note any exclusions. It also does not reference related workflows such as first registering an operator.

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 provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple 'Register' statement by explaining the Oracle-mediated registration mechanism, the absence of Nostr DM challenge-response, and the trust model via GitHub token. It does not detail side effects or reversibility, but the core mutation behavior and process are sufficiently 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 sentences long and each sentence earns its place: the first states the action, the second defines the resource category, and the third explains the registration process. It is front-loaded with the primary purpose and avoids filler or repetition.

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

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

The description explains what an Advocate is, how registration works, and how it differs from related entity types, which is strong contextual coverage for a registration tool. An output schema is indicated, so return-value documentation is not required from the description. Missing details like prerequisites or post-registration effects are minor given the conceptual and process clarity already present.

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

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

Schema description coverage is 100%, so the input schema already documents all five parameters with meaningful descriptions. The tool description adds conceptual context about Advocates but does not add any new detail about parameter formats, constraints, or relationships beyond what the schema provides. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Register a new Advocate in the DPYC community registry.' It further clarifies what an Advocate is and explicitly contrasts it with Operators and certification Authorities, which helps distinguish this tool from siblings like register_operator and register_authority.

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

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

The description provides clear selection context by defining Advocates as non-monetized community utility services, implying this tool is for that category rather than for Operators or Authorities. It also notes that no Nostr DM challenge-response is needed, giving a useful process-based cue. It stops short of explicitly naming alternative tools or stating 'use register_operator instead,' so it lacks full exclusion 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 provided, the description carries the full burden of behavioral disclosure. It does state the key side effect: committing a new 'members/authorities/{npub}.json' file to GitHub. However, it does not mention what happens on duplicate npub, overwrite behavior, authorization requirements, or error conditions.

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

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

The description is well organized: purpose first, then invocation context, then the protocol flow. Nothing is wasted, though the protocol steps could be considered slightly redundant with a dedicated how-to sibling tool. Overall it is focused 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 mutation tool with no annotations, the description covers the essential context: when it is called, who calls it, what it writes, and where it writes it. The output schema covers return values. Gaps around duplicate handling and failure modes keep it from being fully 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?

Schema description coverage is 100%, so the input schema already documents all four parameters meaningfully. The description adds protocol context around npub ownership and upstream sponsorship but does not add significant parameter-level semantics 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 opens with a specific verb and resource: 'Register a new Authority in the DPYC community registry.' It further clarifies the concrete effect by mentioning the GitHub file path committed. This clearly distinguishes it from sibling tools like register_advocate and register_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?

The description gives explicit context for when to call it: at the end of the onboarding protocol, after npub ownership is proven and the Prime Authority approves. It even traces the 3-step Nostr DM flow. It does not explicitly list alternatives or when not to use it, so it misses the top score.

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

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

Annotations are absent, so the description carries the full burden. It does disclose that this creates/registers an Operator entry, that the caller must be an Authority, and that sponsorship follows validation. However, it doesn't state side effects (e.g., a registry record is created), idempotency, failure behavior, or permission requirements beyond the caller being an Authority. Partially transparent but incomplete.

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

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

The description is two short paragraphs: the first sentence states the purpose directly, the second gives the necessary workflow and caller context. There is no filler or redundant repetition of schema information.

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

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

With no annotations and an output schema present, the description provides the essential invocation context (Authority-sponsored, after operator request) and all parameters are fully documented. Minor gaps remain: error behavior, idempotency, and explicit side effects are not described, but for a registration step in a well-defined workflow the description is nearly 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?

Schema coverage is 100% with each parameter having a concise description, so the schema already documents the four parameters. The description adds no extra parameter-level meaning, 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 opens with a specific verb and resource: 'Register a new Operator in the DPYC community registry.' It also clarifies the caller and workflow ('Called by an Authority service after the operator requests registration'), which distinguishes it from sibling tools like register_authority, register_advocate, update_operator, and deregister_operator. No ambiguity about the action.

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

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

It explicitly states when this tool should be invoked: after the operator requests registration, by an Authority service that validates identity and sponsors the call via MCP-to-MCP. This is clear workflow context, though it doesn't name alternative tools or exclusion cases, so it stops short of a perfect 5.

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 transparency burden. It discloses that the tool operates via an automated pull request (suggesting async processing) and that it is not yet implemented. However, it omits side effects, authorization requirements, and what happens after the PR is created, leaving notable gaps.

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 two sentences, front-loaded with the core purpose, and includes a necessary caveat about implementation status. Every word earns its place, with no redundancy or 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?

Although the tool is simple, the description leaves out critical context: parameter meaning, usage guidance, and behavioral details beyond the PR mechanism. The output schema may cover return values, but the missing parameter semantics and lack of when-to-use guidance make the description incomplete for reliable invocation.

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

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

The schema defines a required 'npub' parameter with no description, and the tool description does not mention or explain this parameter at all. Since schema description coverage is 0%, the description fails to compensate, leaving the agent without guidance on how to provide the npub.

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

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

The description clearly states the action ('Citizen self-removal'), the resource (DPYC Social Contract), and the mechanism (automated PR). It distinguishes from sibling tools like confirm_citizenship or request_citizenship by indicating removal rather than addition, and it also flags that it is not yet implemented.

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 usage when a citizen wants to leave the contract, but it provides no explicit when-to-use guidance, never mentions alternative tools, and lacks exclusions or prerequisites. The context is clear but the guidance is implicit.

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 goes well beyond the surface: it explains that a report does not directly set rank, that it triggers an Oracle probe, that a false report costs one probe and changes nothing, and that no caller can demote a healthy relay. This is strong behavioral 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?

The purpose and key caveats are front-loaded, and the sections are logically ordered. A few phrases are somewhat redundant — 'a relay that works needs no announcement' restates 'Report only failures' — but the description remains focused and useful.

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

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

For a tool with four params, no annotations, and an output schema, the description covers purpose, scope, safety, and failure semantics thoroughly. The output schema is stated to exist, so the lack of return-value detail is not a gap.

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

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

Schema description coverage is 100%, and the parameter descriptions already define relay, reporter_npub, signed_event, and mode in detail, including the stateless no-challenge design. The tool description adds behavioral context but not much additional parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Report that a relay in the DPYC set was unreachable, and re-rank it.' This clearly identifies the action and scope, and the added context distinguishes it from read-only or status tools like get_relays or service_status.

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 explicitly says 'Report only failures' and explains why successes should not be reported. It also clarifies in the param description and narrative that the relay must already be in the DPYC set, ruling out arbitrary-host probing. This is clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It openly states that no Authority npub is required or consulted, that a cryptographic challenge is issued, that the nsec never leaves the device, and that the challenge expires in 10 minutes. This is rich context beyond simple 'returns a challenge.' It also describes the patronage identity side effect.

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 several sentences long but each adds value: it defines the flow, disambiguates from the operator path, explains security, and lists return values. It is front-loaded with the primary action and logically structured. Slightly long for a simple registration tool, but appropriately detailed given the security-sensitive nature.

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?

The description covers the full context: actor, target, flow, security mechanism, next step, and timeout. It explains the return values even though an output schema exists, which is helpful. The only aspect not covered is the exact behavior of confirm_citizenship, but that's a separate tool. For this tool's scope, it is 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?

The input schema has 0% description coverage, so the description must compensate. It explains that 'npub' becomes the patronage identity, but it does not explain the 'display_name' parameter at all. The parameter names are self-explanatory, but with only two required parameters and no schema descriptions, the lack of any mention of display_name's intended usage or constraints leaves a gap.

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

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

The description clearly states the action: 'Begin the citizen registration process (Operator-owned flow).' It identifies the specific resource (patron npub registered as Citizen in the DPYC community) and distinguishes it from operator registration, which is a separate sibling flow. The verb 'Begin' and the explicit naming of the citizen path make the tool's purpose 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?

The description explicitly states when to use this tool: 'Called by the Operator on behalf of a patron' and provides an exclusion: 'Not to be confused with operator registration, which goes through the Authority via a Nostr DM delegation request.' It also mentions the next step (confirm_citizenship) and a 10-minute validity window, giving clear operational 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 must disclose behavioral traits. It does a good job stating the return format (npub, url, name) and the data source (upstream_authority_npub). However, it doesn't mention side effects, idempotency, or whether this is a read operation (implied by 'resolve'), leaving some ambiguity.

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 concise—three focused sentences: the first states the action, the second details the return format and data source, the third gives usage context. Every sentence adds value, 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?

Given the tool has 1 parameter, no annotations, and an output schema exists, the description covers the core behavior well. It explains the return structure, data source, and use case. The only gap is not clarifying whether this tool is idempotent or read-only, which would be nice 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?

With 0% schema description coverage and only 1 parameter, the description adds value by implying the npub is an operator npub (via 'operator npub'), which is not stated in the schema. It also provides context that the npub is used to look up the authority. This compensates well for the lack of schema docs.

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

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

The description clearly states the tool resolves the certifying Authority for an operator npub, using a specific verb 'resolve' and resource 'Authority'. It distinguishes well from siblings like 'register_authority' and 'resolve_service', though it could be more explicit about the distinction.

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

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

The description provides explicit use context: 'Use this after bootstrap to learn — and verify — which Authority signed your config, without reading GitHub.' This tells the agent when to use it (after bootstrap) and why (verifying config signing). However, it doesn't explicitly say when not to use it or name alternatives.

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 full burden. It clarifies that 'purchase_mode' is not a price but a topology fact, which is helpful. However, it does not disclose what happens if both parameters are supplied, error conditions, authentication needs, or whether the operation is guaranteed read-only. The description adds value but leaves notable behavioral gaps.

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 sentences: purpose, return fields with clarification, and a usage constraint. It is front-loaded, efficient, and contains no redundant or vague language. 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?

Given the moderate complexity (2 parameters, output schema exists), the description covers the core purpose, return structure, and a key constraint. However, it omits error behavior (e.g., if neither parameter is given) and other potential edge cases. It is mostly complete for a simple resolution tool but could be more thorough.

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 states that the parameters are used to identify a service and that exactly one must be supplied. This adds semantic meaning beyond the schema's type and default. It does not give detailed format guidance, but it sufficiently explains the role and constraint of each parameter.

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

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

The description clearly states the action ('Resolve a DPYC service') and the two possible identifiers (name or npub). It also lists the return fields, which differentiates it from sibling tools like list_services (which lists all services) or lookup_member (which resolves a member). The resource and verb are specific and immediately understandable.

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 usage (when you want to resolve a service by name or npub) and adds a constraint ('Supply exactly one'), but it does not explicitly state when to use this tool over alternatives like list_services or resolve_authority_for. No exclusions or context about when not to use it are provided.

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 behavioral burden and partially fulfills it by adding 'Free, unauthenticated,' which informs about credential requirements and cost. The verb 'report' implies read-only behavior, though it does not explicitly state 'no side effects' or mention rate limits, but for a simple diagnostic tool this is adequate.

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 two sentences, front-loaded with the action label 'Diagnostic:' and a direct statement of what it reports. The second sentence adds a use case and access note. Every word earns its place, with no redundancies or 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?

Given the tool has no parameters, has an output schema, and is a read-only diagnostic, the description sufficiently covers purpose, usage context, and access constraints. It mentions the scope ('this service') and the ecosystem context ('DPYC ecosystem'), making it complete for an agent to select and invoke.

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 has zero parameters and the schema is empty, so no parameter explanation is needed. Per the baseline rule for 0 params, this scores 4. The description adds no parameter-related information, but none is required.

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

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

The description opens with 'Diagnostic:' and states 'report this service's software versions and runtime info,' using a specific verb ('report') and a clear resource ('this service's software versions and runtime info'). It distinguishes itself from sibling tools like network_versions by explicitly scoping to 'this service' rather than the network.

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

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

The description provides a concrete use case ('Use to verify deployment versions across the DPYC ecosystem') and mentions the free/unauthenticated access, giving clear context for when to use it. However, it does not explicitly mention alternative tools or when not to use it, so it lacks full exclusion 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 disclosure burden. It does disclose an important behavioral constraint: 'Must be called by the sponsoring Authority (or any Authority).' It also implies a mutation by 'Update,' and the schema's 'leave empty to keep current' notes add clarity about non-destructive partial updates. It could mention side effects or reversibility more explicitly, but the key permission context is present.

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 compact and front-loaded with the core purpose, followed by concrete usage triggers and an authorization note. Every sentence contributes useful information, with no redundancy or 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?

The description is sufficiently complete for an agent to understand what the tool does, when to use it, and who may call it. An output schema exists, so return values do not need to be described. A slight gap is the lack of explicit alternatives or exclusion criteria, but the existing-entry framing largely covers that.

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 four parameters well. The description adds narrative context for service_url and display_name via the scenarios, but it does not meaningfully exceed 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 uses a specific verb and resource: 'Update an existing Operator's registry entry.' It clearly distinguishes this from register_operator and deregister_operator by emphasizing 'existing' and by listing concrete scenarios like moving to a new MCP endpoint or changing a display name.

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

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

The description gives explicit contexts for use: endpoint changes, display name changes, and registration corrections. It also states the authentication requirement. However, it does not explicitly say when not to use it or contrast it with register_operator/deregister_operator, so it stops short of a full 5.

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 indicate safety and side effects. It implies a read-only operation via 'Identify' and 'Returns', but it does not explicitly state that it makes no changes, nor does it mention any authentication or rate-limit requirements. For a simple query, this is adequate but not comprehensive.

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 two concise sentences with the purpose front-loaded and no redundant or extraneous details. Every word 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?

Given that this is a simple query tool with no input parameters and an output schema, the description fully covers the tool's purpose and expected output. No additional context is necessary for an agent to use 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?

The tool has zero parameters, so the schema completely covers the input. The description adds value by specifying the output fields (npub, display name, member record), which goes beyond the empty 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 clearly states the action ('Identify') and the specific resource ('First Curator (Prime Authority)'), and it lists the exact return fields. This makes it distinct from sibling tools like lookup_member, which focus on general member lookups.

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 tool's narrow purpose makes its usage fairly self-evident, but the description does not explicitly state when to use it versus alternatives or mention any exclusions. For a simple query tool, the implied usage is clear but not spelled out.

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