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 disclosing behavioral traits. It clearly states that deregistration 'removes the member file entirely' and 'returns the Operator to initial state,' which conveys the destructive nature and side effects. It also specifies the authority permission requirement ('must be a registered authority or prime_authority'), adding significant transparency beyond the schema.

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

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

The description is concise and well-structured: a one-line primary purpose, a brief trigger/context explanation, and a clear parameter list. Every sentence adds value without unnecessary padding, and the information is 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?

The description covers purpose, trigger, side effects, permissions, and parameters. It does not mention explicit preconditions (e.g., whether the operator must already exist) or error behavior, but given the output schema exists and the tool is relatively simple, it is nearly complete. Minor gaps prevent a perfect score.

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 does so thoroughly with a dedicated Parameters section that explains both `operator_npub` and `authority_npub`, including the meaning of each and a constraint on the authority role. This fully covers the missing schema documentation.

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

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

The description opens with a specific verb and resource: 'Remove an Operator from the DPYC community registry.' It further clarifies the exact trigger ('Called when an Authority disowns an Operator') and distinguishes from sibling tools like register_operator or renounce_membership by emphasizing the Authority-driven deregistration process.

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 ('Called when an Authority disowns an Operator'), but it does not explicitly mention exclusions or alternatives. Nonetheless, the usage context is unambiguous enough for an agent to select this tool over siblings.

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

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

With no annotations 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 the burden of behavioral disclosure. It explains the 'format' parameter's two possible values, giving some insight into output behavior, but does not mention error cases, side effects, or access requirements beyond the arguments.

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 succinct and well-structured, opening with a one-sentence purpose followed by a clear args list. Every sentence adds value, and there is no redundant or extraneous 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?

The description adequately covers the retrieval scenario, all parameters are explained, and an output schema exists so return values need not be explained. However, it lacks context about when to use this tool versus related list/publish tools, which is a minor gap in completeness.

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 provides meaningful definitions for all four parameters, including the author_npub, operator_npub, slug, and the behavior of the 'format' parameter with its two values, which goes well beyond 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 uses the specific verb 'Retrieve' and names the resource 'published pricing campaign,' clearly stating the tool's function. However, it does not explicitly distinguish from sibling tools like list_campaigns or publish_campaign, relying on the argument semantics to imply specificity.

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 no guidance on when to use this tool versus alternatives such as list_campaigns or publish_campaign. It only states what the tool does and describes parameters, leaving the agent to infer usage context.

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?

No annotations are provided, so the description carries the burden. It does add behavioral context by specifying 'published' campaigns and the optional filtering, but it does not disclose whether the operation is read-only, requires authentication, or has rate limits. The verb 'List' implies read-only, but safety and side effects are not explicitly stated.

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

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

The description is succinct, front-loaded with the main purpose, and wastes no words. The parameter explanations are directly under the summary and follow a clear structure.

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 output schema exists, so return values are covered. The description explains the core function and parameters adequately for a simple listing tool. Minor gaps include lack of pagination behavior and explicit usage guidance versus alternatives, but these are not critical given the tool's 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 input schema only defines types and defaults, with 0% coverage. The description compensates by explaining each parameter's purpose: operator_npub filters by operator, author_npub filters by author. This adds meaningful semantic context 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 uses the specific verb 'List' with the resource 'published pricing campaigns' and scope 'from the DPYC community'. This clearly distinguishes the tool from siblings like get_campaign (single campaign) and publish_campaign (creating 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?

The description provides clear context for usage: listing published campaigns with optional filters. It implies this is the tool to use when you need a list of campaigns, but does not explicitly mention alternatives or when not to use it. However, the purpose is obvious from the verb and parameters.

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 fully carries the behavioral disclosure burden. It explicitly states that the tool is free, unauthenticated, resilient with per-service timeouts, partial results, brief caching, and registry-only fallback. It also clarifies that service descriptions are not hardcoded, which is important for setting expectations about data freshness and origin.

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 front-loaded with the core purpose and then provides concise, relevant details about behavior, resilience, and parameters. The Args section is clearly formatted and every sentence adds value, avoiding unnecessary verbosity.

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

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

For a read-only enumeration tool with an output schema, the description covers all essential context: what the tool reads, how probing works, failure handling, authentication/cost, and parameter options. The reference to check_price and the fallback behavior fills gaps that an agent would otherwise need to infer.

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%, but the description compensates completely. It explains that probe controls whether each endpoint is handshaked and that kind filters by role, listing the valid values: all, operator, authority, or advocate. This gives the agent everything needed to use the parameters 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 opening sentence clearly states the tool's purpose: 'Enumerate the live DPYC service network with self-described summaries.' It uses a specific verb and resource, and the description distinguishes it from sibling listing tools by focusing on live network services and their self-descriptions.

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 practical guidance: probe=True performs a live handshake, while probe=False gives a fast registry-only listing. It also explains the registry-only fallback behavior when endpoints are unavailable. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool.

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

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

With no annotations, the description carries the full burden. 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 burden and does disclose that the tool writes two files and has fallback behavior for optional parameters. However, it omits details about side effects, reversibility, permission 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-structured and front-loaded. It immediately states the purpose, then details the file outputs, and ends with a clear Args list. No unnecessary words are 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?

The description covers the action and all parameter semantics, and the presence of an output schema reduces the need to explain return values. It could be more complete by mentioning potential side effects or failure modes, but overall it is adequately detailed.

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 zero descriptions for parameters, but the description compensates fully by explaining every parameter, including optional parameters and their derived defaults.

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 'Publish a pricing campaign to the DPYC community,' using a specific verb and resource. It further specifies that it commits JSON and Markdown files, distinguishing it from sibling 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?

The intended usage is implied through the action verb and target, but no explicit guidance is given on when to use this tool versus alternatives, nor are there exclusions or scenarios where other tools should be preferred.

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 present, so the description carries the full burden. It discloses the Oracle-mediated trust mechanism, that no Nostr DM challenge-response is required, and that the Oracle operator trusts via GitHub token. It does not explicitly state side effects or reversibility, but the registry context makes the write nature 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 well-structured: a one-sentence purpose, a brief contextual paragraph, a trust-model sentence, and a bulleted parameter list. No redundant information, though the parameter list could be considered expected content.

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

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

The tool has 5 required parameters, no annotations, and an output schema. The description covers the domain role, trust model, and all parameters, giving enough context for an agent to select the tool and construct a call. It doesn't mention any preconditions for the caller beyond the Oracle's trust, but that appears environmental.

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 provides no descriptions (0% coverage), so the description's parameter list is the only source. It gives each of the 5 required parameters a clear, non-obvious meaning, including a concrete example for service_name ('tollbooth-oauth2-collector').

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 'Register a new Advocate in the DPYC community registry,' stating the exact action and resource. It further distinguishes Advocates from 'monetized Operators or certification Authorities,' aligning with sibling tool names and making the 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 characterizes Advocates as 'community utility services... not monetized Operators or Authorities,' giving clear guidance on which entity this tool is for. It also notes 'Oracle-mediated registration — no Nostr DM challenge-response needed,' contrasting with alternative flows. However, it doesn't name specific sibling tools as 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 discloses the key side effect: 'Commits a new members/authorities/{npub}.json file to dpyc-community on GitHub.' It also mentions the approval prerequisite. However, it does not address idempotency, error handling, or what happens if the file already exists, leaving some behavioral transparency 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 logically structured with a summary, protocol context, numbered steps, and parameter definitions. It is longer than necessary but every section adds value; the front-loaded purpose sentence makes it easy to scan.

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

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

For a complex multi-step registration tool, the description covers the protocol flow, prerequisites, and parameter semantics. An output schema exists, so return details are not required. It provides enough context for an agent to invoke it correctly within the larger workflow.

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

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

Schema coverage is 0%, but the description provides a dedicated 'Parameters' section that explains each of the four parameters in plain language (e.g., 'authority_npub: Nostr npub of the new Authority curator'). This fully compensates for the lack of schema 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 opens with a clear action: 'Register a new Authority in the DPYC community registry.' It identifies the specific resource (Authority) and distinguishes itself from sibling tools by detailing its role in the onboarding protocol and the GitHub commit side effect.

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

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

Explicitly states it is 'Called by an Authority service at the end of the onboarding protocol' and lists the exact 3-step Nostr DM flow with sibling tool names, giving clear when-to-use context. It also notes the upstream_authority_npub must already exist, which is a prerequisite.

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

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

With no annotations, the description carries the burden of disclosing behavioral context. It explains the workflow (Authority validates and sponsors via MCP-to-MCP) and the prerequisite that authority_npub must already exist. However, it does not mention side effects, error handling, idempotency, or authorization details beyond the calling context. 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 front-loaded with the primary action and then provides necessary context and parameter explanations. It is somewhat longer than a minimal description, but every sentence adds value—especially the inline parameter list, which is needed given the schema lacks descriptions. No unnecessary 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 4-parameter registration tool with no annotations, the description covers purpose, calling context, parameter semantics, and a key prerequisite. It does not address potential errors or failure modes, and the output schema (if present) would handle return details. Overall, it is quite complete, though some edge-case behavior is unmentioned.

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 provides no descriptions for any of the 4 parameters (0% coverage). The description fully compensates by listing each parameter with a clear explanation, including the constraint that authority_npub must already exist. This is essential and well-executed.

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: "Register a new Operator in the DPYC community registry." It uses a specific verb+resource and distinguishes from siblings like deregister_operator, update_operator, register_advocate, and register_authority by focusing on the Operator registration workflow. The context about being called by an Authority service further clarifies its specific role.

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 the tool: "Called by an Authority service after the operator requests registration." It also provides a prerequisite for the authority_npub parameter, implying that only existing authorities should call it. However, it does not explicitly mention alternatives or when not to use, so a score of 4 is appropriate.

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?

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?

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?

With no annotations, the description carries the full burden. It discloses an important auth requirement and explains partial-update behavior ('leave empty to keep current'). It doesn't describe error conditions or whether the operation is idempotent, but given the presence of an output schema, it provides meaningful 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 opens with a one-sentence summary, followed by a concise usage paragraph and a clear parameter list. Every sentence contributes, and the structure is easily scannable.

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 (mutation auth) and the presence of an output schema, the description covers all essentials: purpose, use cases, auth requirement, and parameter semantics. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must compensate. It provides detailed explanations for all four parameters, including the meaning of empty strings (keep current) and the authority role constraint, adding significant value beyond the raw 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 'Update an existing Operator's registry entry' with specific use cases ('moves to a new MCP endpoint, changes its display name, or needs to correct a registration'). This distinguishes it from siblings like register_operator and deregister_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 says 'Used when...' and provides a precondition ('Must be called by the sponsoring Authority (or any Authority)'). However, it does not explicitly mention alternatives or when not to use, though the 'Used when' list implicitly differentiates from sibling tools.

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

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

With no annotations, the description 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.