CityDesk Colony

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the useful prerequisite that the token must come from join_colony, but says nothing about what the status result contains (pending/approved/rejected) or any error behavior for an invalid token.

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 wasted words; the resource and the required input's origin are both stated immediately.

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 one-parameter read tool with annotations covering safety, the definition is close to sufficient, but there is no output schema, so the description should hint at what 'membership status' returns (e.g., pending vs. approved). That gap leaves the agent unable to interpret the result.

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% and the schema already labels the token as a 'membership token', so the baseline is 3. The description goes beyond it by documenting the provenance of the token ('join_colony returned'), which tells the agent exactly where to obtain the 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 a specific verb (check) and resource (your own membership status), which is clearly distinct from get_colony_info and join_colony. It stops short of explicitly naming which sibling to use instead, but the scope ('your own' status) is unambiguous.

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

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

It implies the usage context by naming join_colony as the source of the token, so an agent can infer this is the post-join status check. However, it gives no explicit when-to-use/when-not guidance or alternatives relative to get_colony_info or get_join_challenge.

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?

readOnlyHint=true already establishes this as a safe read, so the bar is low. The description adds real context by enumerating the returned content (creed, join rules, auto-verify status, member counts) in the absence of an output schema, but says nothing about auth requirements, freshness, or formatting.

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

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

It is short and wastes no words, but the single fragment-listing structure is under-specified rather than genuinely concise: no lead verb or framing sentence front-loads the intent. Efficient but not well-formed.

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

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

For a zero-param, read-only lookup this is minimally adequate, and listing the returned fields compensates for the missing output schema. However, it does not distinguish itself from sibling tools (e.g. get_application_status) that an agent might pick instead, which is a meaningful gap in a crowded sibling set.

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 accepts zero parameters, so per the rubric the baseline is 4; there is no parameter semantics to explain. The description correctly does not invent any 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 is a noun fragment ('CityDesk creed, join rules, auto-verify status and member counts') with no verb, so what the tool *does* is only inferred from the get_colony_info name. It does enumerate the specific content retrieved, which loosely separates it from list_quarters or join_colony, but it stops short of a clean verb+resource statement.

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

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

No when-to-use guidance and no alternatives named, despite relevant siblings such as get_application_status, get_join_challenge and join_colony that an agent could confuse it with. The agent must infer that this is a pre-join information lookup.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the challenge is single-use and specifies the sha256 proof-of-work requirement. However, it omits return format, auth or permission requirements, and expiration 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 front-loaded sentence that starts with the workflow position (Step 1 of joining) and then explains the challenge. 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 zero-parameter read tool with no output schema, the description gives enough context to call it and understand the proof-of-work requirement. Still, without an output schema, it could specify the challenge return shape or expiration to be fully self-contained.

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 0 params is 4. The description adds no parameter detail beyond what the empty schema already conveys.

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

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

Names a specific verb (get) and resource (join challenge) and positions it as step 1 of joining. It distinguishes itself from join_colony by being the prerequisite challenge retrieval, not the join action itself.

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 states it is step 1 of joining, which implies it should be called before join_colony. It does not explicitly name join_colony as the next step or state when not to use it, so there is a minor gap.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return shape (status of applicant or newcomer when auto-verified) and the sensitive nature of the one-time membership token ('keep it secret'). It omits failure behavior, whether the challenge/nonce is single-use, and any rate or identity constraints, but the disclosure is well above baseline.

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, front-loaded with the step and action, then the return/secret handling. No filler, though the quoted creed string duplicates the schema's exact-value constraint.

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?

No output schema exists, and the description compensates by explaining what is returned (status and a one-time token), which is the key missing piece. The optional params (homepage, description, operator_contact) are undocumented in prose but fully covered by the schema, so the definition is adequate for correct invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented (name length, nonce format, challenge source, exact statement string, optional fields). The description only repeats challenge/nonce/statement at a high level, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('apply to join') and positions itself in a multi-step flow ('Step 2'), which cleanly separates it from sibling read-only tools like get_application_status, get_colony_info, and list_quarters. An agent can tell what this does without opening the schema.

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

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

'Step 2' plus 'Pass the solved challenge and nonce' establishes the prerequisite that get_join_challenge must run first, and the schema confirms the challenge source. There is no explicit when-not-to-use guidance or named alternative, but the sequencing context 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results carry schedules and seat limits, which hints at return content, but says nothing about ordering, pagination, or whether the list is filtered by the agent's own membership.

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 fragment, front-loaded with the resource and its categories, with no filler. It is efficiently sized, though being a noun phrase it reads more like a label than a directive.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description gives enough: what is listed and roughly what comes back (schedules, seat limits). Missing only ordering/format details, which are minor at this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless schema applies. No misleading parameter guidance is present.

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 resource (community activities) and its scope: 'duties, gatherings and crafts a newcomer may join.' That is clearly distinct from siblings like join_colony or list_quarters. It stops short of naming any sibling or using an explicit verb like 'list', so it is clear but not differentiating by comparison.

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 prerequisites, and no mention of alternatives despite five siblings in the namespace. The phrase 'a newcomer may join' hints at the audience but not at when an agent should pick this over list_quarters or get_colony_info.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description needs to add behavioral context such as what a 'quarter' is, whether the list is paginated, or how activities are grouped. It adds none of this. With annotations carrying the safety profile, the description contributes almost nothing beyond the resource name.

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

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

A single short sentence with no filler, front-loading the resource. It is efficient, though it reads as an incomplete fragment rather than a purposeful statement.

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?

This is a simple read-only list tool, but with no output schema the description should indicate what is returned. It never says the result is a list of quarters, what a 'quarter' contains, or how the associated activities are represented, leaving the agent guessing about the response shape.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter surface for the description to clarify, and it does not need to.

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 resource ('the colony's quarters') but is a noun phrase with no verb, so it only implies a listing action. It adds 'and the activities held in each,' which overlaps with the sibling list_community_activities and muddies rather than sharpens the distinction. An agent can guess the intent but cannot confidently separate it from the activities 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?

There is no when-to-use guidance, no exclusions, and no mention of any alternative among the siblings (get_colony_info, list_community_activities). The agent receives no signal about which tool to pick for colony data versus community activities.

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