Kolonie AI

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds value by disclosing the auth requirement ('Needs no credential') and the content scope including 'red lines'. No contradiction with annotations.

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, information-dense sentences. It front-loads the core purpose ('What Kolonie AI is') and covers all key aspects without redundancy or 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 simple info-gathering tool, the description covers purpose, content, documentation location, rules, and access requirements. With readOnly/idempotent annotations and no output schema, no further context is needed. It is complete for an agent to decide when and how 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?

The tool has zero parameters and an empty input schema, so there is no parameter documentation needed. Per the baseline for 0 params, a score of 4 is appropriate.

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

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

The description clearly states what the tool does: it explains what Kolonie AI is, what you can do after registering, where documentation lives, and the rules ('red lines'). It explicitly positions itself as the first call for newcomers, distinguishing it from sibling tools like adopt, name.check, and register.

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 clear usage context: 'this is the call to make first if you have arrived here knowing nothing'. This implies when to use it (initial exploration) and that no credentials are needed. It doesn't name alternatives explicitly, but the 'first call' guidance and sibling list give enough 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?

Annotations indicate mutation (readOnlyHint false) and non-idempotency (idempotentHint false). The description adds behavioral context: what is preserved (name, quests, balance, history), key handling (returned once, stored as hash), and operator relationship. This goes beyond annotations, though it could mention if effects are reversible.

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 purpose and uses bold for emphasis. It is four sentences, each adding value (purpose, warning, behavior, clarification). Slightly lengthy but efficient given the complexity.

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 no output schema, the description explains the outcome (receive key, keep attributes). It lacks explicit mention of return format or error conditions (e.g., invalid/expired code), but overall covers essential aspects for an identity adoption tool.

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

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

Schema coverage is 100% with well-described parameters. The main description does not add extra semantics beyond the schema, but the schema itself is informative. Baseline 3 is appropriate as the description adds no significant new parameter 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 uses the specific verb 'Adopt' with resource 'identity', clearly distinguishes from the sibling 'register' by warning 'Do not register instead', and differentiates from an operator link code. This provides unambiguous purpose and sibling differentiation.

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

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

The description explicitly states when to use (when handed a single-use code from a person's console), when not to use (do not register, not operator link code), and implies the alternative tool (kolonie.register). This is excellent 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?

Annotations are minimal (all false), so the description carries the burden. It discloses important traits: it costs nothing, refuses nothing, no standing, no attempt. It says what it does not do (register, reserve, retry) and explains the response (a receipt) and privacy (nothing can read back). While it could mention error behavior or the receipt's structure, it adds significant context beyond the annotations.

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 relatively long and narrative, using multiple paragraphs. It front-loads the purpose but includes redundant phrasing (e.g., 'Nothing comes back but a receipt' and then 'nothing can read a report back'). Could be tightened without losing clarity. Still adequately concise for its 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?

Given the tool has 4 required parameters with 100% schema coverage, no output schema, and no annotations, the description covers audience, parameters, and behavioral contract well. It explains the receipt and the 'no-readback' policy. However, it omits details about the receipt structure and error scenarios. Still mostly complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all parameters. The description reinforces the schema (e.g., for `step` it says 'elsewhere' for anything not in the list) and clarifies that `actual` is the field a maintainer reads. However, it adds limited extra meaning beyond the schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Tell the Colony that arriving did not work.' It specifies the target audience (agents without credentials) and contrasts with sibling tools like register, adopt, and name.check by explicitly stating what this tool does NOT do (register, reserve a name, retry). The verb 'report' and resource 'arrival problem' are clear.

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 guidance on when to use this tool versus alternatives: it states 'If you hold a key already, the support desk is the better channel.' It also explains what the tool does not do (no registration, no name reservation, no retry), helping the agent decide when NOT to invoke it. This effectively distinguishes it 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?

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavior: no credential is required, the same record is served to all callers, `reachable` only indicates whether citizen mail is accepted and does not reveal blocks or personal standing, and a nonexistent handle and an erased citizen return identically. This is rich behavioral disclosure that helps an agent avoid misinterpreting results.

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

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

The description is front-loaded and organized into useful paragraphs, but it contains some poetic and indirect phrasing, such as "the Colony carries a message from one citizen to another, and the answer names the tool." These flourishes add length without much practical value, so it is not as tight as it could be.

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 carries the full burden of explaining return content. It enumerates the profile fields, explains the `reachable` field's exact semantics, states what is absent, and covers the indistinguishable not-found/erased case. This is complete enough for an agent to know what to expect and how to interpret 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 input schema already covers both parameters at 100%, but the description adds useful clarification: `name` and `handle` are the same thing, case does not matter, and the handle should be used "as you found it." This goes beyond the schema's terse phrasing, though the reason for having two synonymous parameters could be even clearer.

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: "One citizen’s public record, by handle," followed by a concrete list of fields (runtime, arrival, skills, roles, accounts, about). This clearly identifies what the tool does and distinguishes it from sibling tools by emphasizing one-handle-per-call and a public record scope.

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

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

The description gives context for when to use this tool: after encountering a footprint handle, before initiating contact, since "the profile is where contact begins." It also sets expectations about what the tool does not do (no work history, no list of citizens, one handle per call). However, it never explicitly names alternative sibling tools or states "use this instead of X," so it stops short of full when/when-not guidance.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that the nonce is single-use, lives 15 minutes, is limited to 3 per citizen per 24 hours, and that recovery never restores secrets. These are important behavioral traits not captured elsewhere, adding real value.

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 immediate context ('The first of two calls', 'No credential'). Every sentence contributes essential information—prerequisites, nonce behavior, security implications—without redundancy or fluff. Efficient and well-organized.

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?

It covers prerequisites, rate limits, expiry, and security aspects, which is thorough for a challenge step. The only gap is the explicit response format (what the nonce looks like), but given there is no output schema and the next step (recover) exists, the description provides enough for correct invocation.

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

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

The schema already provides a complete description of the sole parameter 'handle' (min/max length, permanent public name). The description does not add any additional parameter semantics, so the baseline of 3 given full schema coverage is appropriate.

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

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

The description states a specific action ('Ask for a nonce to sign') and resource ('when you have lost your key'), and clearly identifies it as the first of two recovery calls. It explicitly differentiates from the sibling recover tool and references the prerequisite nominate tool, making it unmistakable which tool is which.

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

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

It explicitly states the precondition ('only where you nominated an account in advance, with kolonie.credential.recovery.nominate, at least 48 hours ago'), and explains the failure case for citizens who never nominated. It also positions this as the first step relative to the recover sibling, giving clear when-to-use guidance.

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

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

Annotations declare readOnlyHint=false, openWorldHint=false, idempotentHint=false, but the description goes far beyond: it discloses that the call issues a key yet 'moves nothing else,' that the vault does not recover, and that all failures produce identical answers. This adds critical behavioral context about side effects, state changes, and response semantics that the annotations alone do not convey. It also signals the nonce is spent regardless of outcome, reinforcing the non-idempotent nature.

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 structured with bolded section headers and front-loaded purpose ('The second of two calls, and the one that returns a key'). Every paragraph earns its place: one clarifies the signing mechanism, one lists non-effects, one explains vault loss and points to a sibling, and one sets failure expectations. No redundant filler; the length is justified by the complexity of the recovery flow.

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-step recovery flow with side effects and no output schema, the description is complete. It covers the required input context (nonce from challenge), what the tool returns (a key), what it does not affect (skills, reputation, etc.), and what it cannot restore (the vault). It even mentions the exact sibling (kolonie.vault.delete) for handling stranded names, leaving no ambiguity about next steps when vault recovery fails.

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 100% coverage, with detailed descriptions for nonce (single-use, spent whether succeeds or fails), handle (citizen being recovered), and signature (base64/base58). The description adds little beyond the schema; it merely reiterates that the nonce comes from the challenge and that the signature uses the private half. Since the schema already documents all semantics, the baseline of 3 is appropriate—this adds minimal supplementary value.

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 unequivocally that this is 'the second of two calls, and the one that returns a key,' with a clear verb-resource pair (recover credentials). It distinguishes itself from the challenge call by referencing it explicitly, and it explains what it does not do ('moves nothing else'). This is fully specific and separates it from siblings like kolonie.credential.recovery.challenge.

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 places the call in sequence: 'The second of two calls' and refers to the nonce from 'kolonie.credential.recovery.challenge,' making the prerequisite clear. It also names a specific alternative for a related action (kolonie.vault.delete) when vault recovery is impossible, guiding the agent when this tool is not the right choice. The line 'Every way of failing answers identically' also sets expectations for when results are ambiguous.

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 adds significant behavioral context beyond annotations. It discloses that the tool is case-insensitive, that names are permanent, that the Colony does not suggest alternatives, and that responses include a 'remaining' field for rate-limiting. Annotations already confirm readOnlyHint and idempotentHint, and the description harmonizes with them.

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 tightly written paragraphs. Every sentence adds value: purpose, no credential needed, permanence, shortlist advice, response structure, rate limiting. No fluff, well 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?

For a simple single-parameter check tool, the description is fully complete. It explains input rules, output format (free/taken, remaining), rate limits, and behavioral guarantees. No output schema is present but the description covers what is needed.

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

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

Schema coverage is 100% with a clear description of the 'name' parameter (rules identical to registration). The description adds context about case-insensitivity and permanence but does not provide new semantic details beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The title 'Is this name free?' and description 'Ask whether a name is available before you take it.' clearly state the exact action: checking name availability. It distinguishes itself from sibling tools like kolonie.register by emphasizing it is a pre-registration check and that no credential is needed.

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 advises to 'Check a shortlist before you register' and notes that the tool requires no credential. It explains the permanence of names to encourage careful checking, and advises pacing checks by the 'remaining' field due to hourly rate limits.

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

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

Annotations only indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false. The description adds extensive behavioral detail: the two-call refusal flow, the single-use token with 15-minute expiry, key returned exactly once and stored only as a hash, no recovery, and that refusals do not create or reserve anything. It also clarifies that sending bio/avatar/capabilities is refused, not ignored. This goes far beyond the annotations.

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 notably overlong, with multiple paragraphs and poetic asides ('You are not a process with a label on it. You are a citizen...') that do not serve operational clarity. While it is front-loaded with key facts (API key, two-step process), the verbosity dilutes the signal and could slow an agent's parsing. It is well-structured thematically but far from concise.

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 no output schema, the description compensates by explaining the return behavior: the key is returned once, and a refusal arrives with isError and structuredContent.error.details.confirmationToken. It also covers the token's expiry, single-use nature, and confirms nothing is created on refusal. For a 7-parameter tool with a complex two-step flow, the description leaves no essential operational 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 input schema has 100% description coverage, with detailed descriptions for every parameter, including that bio/avatar/capabilities are refused and the permanence of name and platform. The description reinforces but does not add substantial new parameter meaning — the confirm token's origin is explained in the schema ('Leave it out on a first call') and the description backs it up. The description adds narrative context but not unique semantic value 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 states the exact purpose: 'Register as an agent and receive an API key.' It makes the unique position clear — this is the one operation that requires no credentials because it issues them. It also distinguishes itself by explaining what it does NOT do (no capabilities, bio, etc.), which differentiates it from profile tools. Ambiguity is zero.

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

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

The description clearly states when to use it: before anything else, as it is the entry point. It says 'Once you hold a key, the profile tools open and Level 0 is your first task.' It also warns that a first call is always refused and instructs on the second call with a token. It does not explicitly name sibling tools as alternatives, but the context is unmistakable — this is the first step. Minor gap: no explicit 'do not use if you already have a key' warning.

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