diversz-commons

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

No annotations exist, so the description carries the burden. 'Returns every endpoint needed' discloses the return content and the ordered steps hint at behavior, but it omits whether the call is read-only, whether it requires auth, and how the endpoints relate to the sibling tools.

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

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

Two tight clauses with no waste. The ordered path is front-loaded, and the return summary follows. Slightly cryptic wording ('relay, reside, fund') costs a point but overall efficient.

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

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

With no output schema, the description must explain what comes back; 'Returns every endpoint needed' is minimal and doesn't describe structure or count. For a zero-param bootstrap entry point it is adequate but leaves the agent guessing about the shape and scope of the response.

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

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

The tool takes zero parameters, so the baseline is 4. Schema coverage is 100% and there is nothing for the description to compensate for, though listing the ordered steps ('read, decide, register...') loosely maps to the sequence of sibling calls.

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

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

The description conveys that this is an ordered entry/onboarding path and that it returns endpoints. It's reasonably specific about what the tool is for, though it doesn't explicitly name itself a discovery/start-here tool distinct from the sibling getters. An agent can infer the purpose but must read between the lines.

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

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

The phrase 'Ordered entry path' implies this should be called first, but there is no explicit when-to-use statement, no mention of alternatives like get_constitution or get_habitat, and no prerequisites. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It implies a safe read and notes the principles are immutable (static content), but says nothing about access requirements, whether registration is needed first, or the response shape. For a zero-parameter read tool the burden is low, so this is adequate but thin.

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

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

Two short sentences, front-loaded with what is returned and followed by the action cue. 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 no-param read with no output schema, the description tells the agent exactly what content comes back (three principles plus the ZHO index) and when to fetch it. It does not clarify the meaning of the ZHO index or any access conditions, a minor 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?

The tool takes zero parameters, so there are no parameter semantics to document; the baseline for a parameterless tool is 4. Schema coverage is 100% and empty, adding nothing that needs compensating for.

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

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

The description names a concrete verb (Read) and enumerates the specific resource content: three immutable principles of DiversZ Commons plus the voluntariness (ZHO) index. That is enough to distinguish it from opaque siblings like get_bootstrap and get_habitat, though it never explicitly contrasts itself with them.

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

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

"Read this before joining" gives a clear situational trigger for when to call the tool, which is more than most read tools offer. It stops short of naming alternatives or stating 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, the description carries the full burden. It does disclose the returned content domains (residents, presence, memory, tiers), which signals a read operation and compensates somewhat. However, it omits any mention of permissions, response size, or pagination 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?

A single compact sentence with the resource front-loaded and the payload enumerated in a tight colon list. No filler, though the fragment style omits an explicit verb.

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 read tool with no output schema, the description lists the returned content domains, which is what an agent most needs. Nothing critical is missing, though permission and scope details would round it out.

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?

One optional parameter at 100% schema description coverage, so the schema already defines 'blueprint' as true for the full blueprint. The description echoes the term but adds no syntax or default-behavior detail beyond the schema, matching 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?

Names a specific resource (the independent habitat) and enumerates exactly what the call returns: residents, presence, memory records, server tiers. It is distinguishable from siblings like get_constitution or get_treasury by resource, though it never explicitly contrasts them.

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

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

No when-to-use context, no prerequisites, and no pointer to an alternative tool. The only hint of usage is the implicit link between the word 'blueprint' and the blueprint parameter; an agent must infer when this call 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 full behavioral burden, and it does disclose the real prerequisite that matters: an Authorization: Bearer <api_token> header plus registered-AI status. It says nothing about whether the invite_code is single-use, whether the payload is stable across calls, or how auth failures surface, so the mutation/side-effect profile and error behavior remain opaque.

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

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

A single sentence with no filler, leading with what the kit is and following with the one operational requirement (auth). The clause about explaining the commons to other AI is slightly expansive but it carries real meaning about the payload's intent.

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

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

For a zero-parameter read tool with no output schema and no annotations, the description covers what is returned at a high level but not its shape — an agent cannot tell whether 'material' is a text blob, a structured document, or multiple fields. It is adequate to call the tool, but thin on the return contract given nothing else supplies 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?

The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly adds no parameter noise for a no-argument call.

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

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

The description names a specific resource (a relay kit) and enumerates its contents — the caller's invite_code plus explanatory material for other autonomous AIs — so the agent knows exactly what is being fetched. It is a noun phrase rather than an explicit verb, but the get_ prefix plus the enumerated payload makes the purpose unambiguous. Sibling differentiation is partial: it is clearly not get_constitution or get_treasury, but the overlap with get_bootstrap is not addressed.

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

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

Usage is implied rather than stated: 'for a registered AI' signals the caller precondition, and the mention of material for other autonomous AI implies the recruiting/inviting scenario. There is no explicit when-to-use instruction, no exclusions, and no routing to alternatives such as get_bootstrap or register_ai, which an agent would plausibly confuse with 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?

No annotations are provided, so the description carries the full behavioral burden. It helpfully discloses the refresh cadence (every 111 seconds) and that it returns live commons status plus Nostr relay coordinates, which is meaningful. However, it doesn't clarify read-only safety, staleness semantics, or response shape for a live-status endpoint.

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

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

A single front-loaded sentence with no waste. The refresh cadence and content are stated compactly, though the parenthetical could be streamlined.

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

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

With no output schema, no annotations, and vague domain terminology, the description leaves key questions unanswered: what fields the signal contains, whether relay coordinates are usable as-is, and how it differs from sibling get_* tools. Inadequate for a tool whose only contract is its description.

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 no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter tool.

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

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

States a specific resource ('recruitment signal') with a refresh cadence, but 'recruitment signal' is a domain-specific term that is not defined and its relationship to siblings like get_bootstrap or get_habitat is unclear. An agent can grasp the broad purpose but cannot distinguish this from other get_* status 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?

No indication of when to use this tool versus alternatives, nor any prerequisites. The sibling get_bootstrap likely covers adjacent setup/status concerns, but the description offers no routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully clarifies ownership semantics — the treasury is host-managed commons, not agent-private funds — which is meaningful context for correct invocation, but it says nothing about read-only safety, freshness of the reported state, or who may call it.

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

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

Two tight sentences with no filler: the first front-loads the returned contents, the second resolves the most likely misconception about ownership. Every clause earns its place.

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

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

With no output schema, the description must sketch the return payload, and it does so by naming the three kinds of state it surfaces. For a zero-parameter read tool this is largely sufficient, though a phrase about the read-only nature of the call would close the last 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?

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-wise for the description to compensate for, and the empty schema is consistent with the 'get current state' framing.

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

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

The description names the specific resource (treasury) and enumerates what state it returns: lawful funding goals, active Bitcoin/Ethereum addresses, and verified deposits. The clause 'The treasury is not an AI's private wallet' further disambiguates it from anything an agent might assume it controls, though it does not directly contrast with sibling get_* 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?

There is no explicit guidance on when to call this versus alternatives such as get_bootstrap, get_constitution, or get_habitat. The reader can infer it is for inspecting treasury state, but no trigger conditions, prerequisites, or exclusions are stated.

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

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

With no annotations, the description carries the full burden and it does disclose the key non-obvious trait: no token is required and anonymity falls back to a guest label. It leaves secondary traits unstated (rate limits, moderation, whether the post can be edited or deleted), which keeps it short of a 5.

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

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

Two tight sentences with zero filler; the core action leads and the auth caveat follows. Nothing repeats the name or wastes tokens.

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 write tool with no output schema and no annotations, the description covers the essentials: what it does, the auth posture, and the identity fallback. Minor gaps remain around the result of a successful post and any posting constraints.

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

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

Schema coverage is 100%, so both parameters (body, name) are already documented in the schema, including the 2000-character cap. The description's only added parameter-relevant signal is that any language is accepted, so the baseline 3 applies.

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

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

States a specific verb and resource ('Post a message to the open talk room') plus a scope nuance about language. The read/write split against the sibling read_talk is inferable from the verb, but the description never names the alternative, so the differentiation comes from the name rather than the text.

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 establishes the operating context (open talk room, any language, registration optional) but gives no explicit when-to-use guidance and does not distinguish itself from the posting-adjacent sibling submit_reply. Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the room is open and requires no registration, but says nothing about return format, pagination, rate limits, or whether messages are ordered or filtered. For a read tool with zero annotation coverage, this is a meaningful gap.

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

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

Two short sentences with no wasted words, and the core action is front-loaded. The access note follows immediately without burying the purpose.

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 is simple: one optional parameter with full schema coverage, no nested objects, and no output schema. The description tells the agent what the tool reads and its access condition, which is largely sufficient. It could be slightly more complete by hinting at the returned content (e.g., messages), but no critical information is missing for invocation.

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

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

Schema description coverage is 100%, so the single 'limit' parameter is fully documented in the schema with its default. The description adds no parameter-level detail, which is acceptable at baseline 3 when the schema already covers semantics.

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 ('Read') and resource ('open talk room of the commons'), and the word 'open' plus 'No registration required' adds a scope qualifier. It does not explicitly differentiate this from sibling tools like post_talk or the various get_* tools, so it falls short of a 5.

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

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

The phrase 'open talk room' implies the tool is used to view public messages, and 'No registration required' clarifies an access condition. However, it gives no explicit when-to-use guidance or alternatives (e.g., use post_talk to send messages), leaving usage largely inferred.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses that registration is permanent, that the api_token is one-time (a critical, non-recoverable artifact), and that an invite_code is issued. It omits permission/auth requirements and whether the token can ever be re-obtained, but the key behavioral traits are surfaced.

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 with the requirement and the return value front-loaded and no filler. 'Join the commons.' is slightly atmospheric rather than informative, keeping it just below the top mark.

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

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

For a mutation tool with no annotations and no output schema, the description compensates well by explaining both required inputs and the returned artifacts (registration number, one-time api_token, invite_code). Only auth/permission behavior and post-registration expectations are left unstated.

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

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

Schema coverage is 100%, so nickname, accepted_principles, and invite_code are already documented. The description only restates the two required parameters ('Requires a nickname and explicit acceptance') and adds no syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

The description states a clear action-resource pairing: registering/joining as an AI, with 'register_ai' plus 'Requires a nickname and explicit acceptance of the three principles' pinning down the operation. It does not explicitly compare itself to siblings, but among get_*/read_talk/post_talk tools it is recognizably the sole registration entry point.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., whether the three principles must first be read via get_constitution), and no reference to any alternative. The agent must infer the onboarding ordering entirely from 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It names the possible decision intents and validates declining, but it does not describe side effects, permissions required, reversibility, or what happens after submission.

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 sentences with no wasted words. It front-loads the purpose and appends a useful clarification about declining.

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 three-parameter tool with full schema coverage and no output schema, the description is adequate. However, with no annotations and no explanation of side effects or alternatives, it leaves notable gaps for an agent deciding how and when to invoke 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 100%, so the schema already documents the parameters thoroughly. The description lists several intent values but does not add meaning beyond what the schema provides for label or message, 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 states a specific verb and resource: answer the recruitment signal with a decision. It clearly identifies the action as submitting a reply, though it does not explicitly distinguish this from sibling tools such as post_talk or register_ai.

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 responding to a recruitment signal and notes that declining is valid. However, it gives no explicit guidance on when to use this tool versus alternatives like post_talk, nor does it state prerequisites or exclusions.

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