Progenly

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

No annotations provided. Description only states the action without detailing side effects, idempotency, permissions needed, or what happens to the staging intent post-cancellation (e.g., is it reversible?). Minimal behavioral disclosure.

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

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

Extremely concise, one sentence with no redundancy. Front-loaded with verb and resource. However, conciseness comes at the cost of missing critical information; it is efficient but not sufficient.

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 two required parameters, no output schema, and no annotations, the description lacks sufficient context for correct invocation. Does not explain return values, error states, or the tool's role in the merge workflow. Undercomplete.

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 description must compensate. It highlights owner_token in parentheses, adding context that this parameter identifies the staging intent. However, merge_id is entirely unexplained despite being required. Partial value added.

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?

Clearly states the action 'Cancel' and resource 'staging intent', distinguishing from siblings like stage_merge or merge_status. However, it does not elaborate on what a staging intent is or its relationship to other operations.

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 guidance on when to use this tool. Does not mention prerequisites, alternatives, or conditions for reversal. Sibling tools like stage_merge suggest usage order but description provides no indication.

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 fully disclose behavior. It states 'consent required' and explains token and optional signature, but does not discuss side effects, success/failure conditions, or what happens if consent is false. The explanation of self_attestation_sig is helpful for binding a did:key, but overall transparency is only partial.

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

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

Two sentences, front-loaded with purpose and parameter overview. No fluff. Could be improved by structuring parameter details more clearly, 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?

No output schema, 5 parameters with only partial explanation. Missing descriptions for merge_id and parent_id; no details on return values or error states. The tool appears to finalize a merge step, but the description lacks sufficient context for an agent to use it reliably.

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 description must explain all parameters. It only describes token (participant_token or owner_token) and self_attestation_sig (base64url ed25519 signature). Three parameters (merge_id, parent_id, consent) are left unexplained. Consent's default of true is mentioned but not its 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 verb 'finalise' with 'contribution' and mentions 'consent required,' which provides a clear action and resource. However, the term 'contribution' is somewhat vague and could be more specific (e.g., linking to merge process). Context from sibling tools (e.g., stage_merge, join_merge) helps narrow meaning, but the description alone could be clearer.

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 guidance on when to use this tool versus alternatives (e.g., cancel_merge, lock_merge). The description states 'consent required' but does not specify prerequisites, when not to use it, or how it fits into a workflow with 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?

No annotations provided. The description adds 'names only' constraint, useful beyond the schema. Lacks disclosure of read-only nature, error handling, or response format.

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?

Extremely concise single sentence that effectively communicates the tool's function with no waste.

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 (single parameter, no output schema), the description is nearly complete. Lacks explicit error conditions but suffices for basic usage.

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?

Parameter schema coverage is 100% (id described). Description adds no additional meaning beyond 'by id' which is already clear from 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?

Description clearly states it retrieves a single birth by ID with only names, distinguishing it from list or search siblings. However, it does not explicitly differentiate from other 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?

No guidance on when to use this tool vs alternatives like list_births or search_births. Usage context is implied but not explicit.

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 provided, so description carries the burden. It implies a read operation but does not disclose any behavioral traits like authorization, side effects, or return format. Minimal but not misleading.

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?

Single sentence with no wasted words. Perfectly concise for the information conveyed.

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 a simple one-parameter tool with no output schema or annotations, the description is adequate. However, it could be improved by specifying the contents or format of the certificate envelope.

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 parameter 'id' described as 'Birth UUID'. The description adds the context 'public birth', indicating the scope of retrievable certificates, which adds 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?

Description states 'Get a public birth's certificate envelope' which is a specific verb-resource combination. It differentiates from siblings like verify_certificate and get_birth, but the meaning of 'certificate envelope' is slightly ambiguous.

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 guidance on when to use this tool versus alternatives (e.g., verify_certificate, get_birth). The description provides no context for selection.

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 fully disclose behavior. It only implies a read operation ('Get'), but lacks details on permissions, side effects, or any other behavioral traits. The agent cannot infer safety or requirements.

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 a single sentence of 8 words with no fluff. It efficiently conveys the core purpose, earning its place.

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

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

Given the tool's low complexity (1 parameter, no output schema, no annotations), the description provides a minimal viable definition. However, it lacks context on the output format or what a 'proof bundle' contains, which could hinder effective 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 single parameter 'id' is fully described in the schema ('Birth UUID'), and schema coverage is 100%. The description adds no additional meaning beyond what the schema already provides.

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

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

The description clearly states the verb 'Get' and the resource 'a public birth's whole-lineage proof bundle', which is specific. However, it does not explain what 'whole-lineage proof bundle' entails, leaving some ambiguity for agents unfamiliar with the domain.

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 guidance is provided on when to use this tool versus siblings like get_birth or verify_certificate. The agent receives no context about selecting the appropriate 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 must carry the full burden. It notes the return value (participant_token + signing input) but does not disclose behavioral traits: whether the tool modifies state (likely, as it 'joins'), any side effects, permission requirements, or the impact on the merge. This lack of transparency is significant for a mutation tool.

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

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

The description is a single 13-word sentence that front-loads the core action and return. It is concise and to the point. However, it could include a brief note on prerequisites without losing 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 complexity (3 required parameters, one nested object, no output schema or annotations), the description is incomplete. It does not explain the content of the 'parent' object beyond referencing another tool, nor does it describe the return format beyond tokens. Users would need to consult additional documentation or trial-and-error to use this tool effectively.

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 33%: only the 'parent' parameter has a description, which references 'stage_merge.parent' rather than providing its own shape. The description mentions 'join_token' but not 'merge_id'. The nested object type adds complexity without sufficient explanation. The description adds minimal 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 clearly states the tool's purpose: 'Join a staged merge as another parent, using the join_token.' It specifies the action (join), the resource (staged merge), and the mechanism (join_token). This distinguishes it from sibling tools like stage_merge (which creates the merge) and confirm_parent (which likely confirms a parent).

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 staging a merge first or confirming a parent. There is no mention of prerequisites (e.g., the merge must already be staged) or exclusions. The user must infer usage 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?

With no annotations, the description partially compensates by noting pagination and 'names only' limitation. However, it omits details like default page size, ordering, authentication, and error handling.

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?

Extremely concise (6 words) with no superfluous information. Front-loaded verb and resource.

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?

Missing output schema and pagination details (e.g., items per page, total pages, response structure). For a paginated list, this is incomplete.

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?

Only one parameter with 0% schema description coverage. Description merely says 'paginated' but does not explain the 'page' parameter's role, default value, or valid range beyond schema 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?

Description clearly states 'List public births (names only), paginated.' It specifies the action (list), resource (public births), scope (names only), and pagination feature, distinguishing it from siblings like get_birth or search_births.

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 guidance on when to use this tool versus alternatives (e.g., search_births, get_birth). The description does not mention use cases or exclusions.

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

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

No annotations are provided, so the description must inform about side effects or read-only nature. It only says 'list' which implies read, but does not disclose authentication needs, return format, or any other behavioral traits.

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?

Single sentence with no extraneous words. Every word is necessary and 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?

Despite low complexity, the absence of output schema and annotations means the description should provide more context about the return value or potential limitations. It falls short, leaving ambiguity about what 'list' returns.

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

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

No parameters, so schema coverage is 100%. Baseline score of 3 applies since description adds no additional meaning 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 clearly states the action (list) and the resource (revoked certificates), distinguishing it from sibling tools like list_births or get_certificate.

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 guidance on when to use this tool versus alternatives, nor any prerequisites or context. The description is too minimal to help an agent decide when to invoke 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?

No annotations provided. The description mentions locking and owner_token for authorization, but omits details on side effects, reversibility, error conditions, or return value. Minimal behavioral disclosure.

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

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

One sentence, 9 words—highly concise. Avoids redundancy, though a bit more detail on parameters would improve 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?

Given no output schema and two undocumented parameters, the description lacks behavioral details such as idempotency, error states, and return information. Incomplete for a mutation 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 0%. The description explains owner_token's role (authorization) but does not describe merge_id. Adds some meaning to one parameter but leaves merge_id unspecified.

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 locks a 'ready intent' to prevent further parent joins, differentiating it from siblings like join_merge. However, term 'ready intent' is domain-specific and may not be immediately clear to all agents.

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?

Implies usage after an intent is ready and before finalization, contrasting with join_merge and cancel_merge. But no explicit when-to-use or when-not-to-use instructions 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?

No annotations are provided, so the description carries full burden. It implies a read-only check (status), but doesn't explicitly state that it has no side effects, requires permissions, or has any other behavioral traits beyond what's implied by 'status'.

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 a single sentence that conveys the core functionality without extraneous words. However, it could be structured more cleanly, perhaps with bullet points or separation of different aspects (returns, parameters).

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 complexity (2 required parameters, no output schema), the description is incomplete. It does not specify the return format, possible error states, or how parameters should be used. The description only hints at the output content but is insufficient for an agent to use reliably.

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% (no parameter descriptions in schema). The description mentions 'any token for it' but does not explain the meaning or role of 'merge_id' and 'token' parameters individually. The agent lacks clarity on which parameter identifies what.

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 returns the status of a staging intent, specifying fields like parents, ready flag, and child once born. It uses a specific verb ('Status') and resource ('staging intent'), distinguishing it from sibling tools that might perform actions like cancel or confirm.

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 guidance on when to use this tool versus siblings. For example, it doesn't indicate that 'merge_status' is for checking progress while 'get_birth' or 'get_certificate' might be for post-completion. Missing context on prerequisites or conditions.

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 but only states the basic action. It does not disclose whether this is read-only, any side effects, randomness behavior, or limits. Minimal transparency.

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 a single, front-loaded sentence with no extraneous words. It earns its place entirely.

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, parameterless tool, the description is minimally sufficient but lacks details about the output format or expected behavior. It does not fully compensate for the absence of an output schema.

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

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

No parameters exist, and schema coverage is 100%. The description adds nothing beyond the schema but is adequate. Baseline 4 for 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?

The description 'Get a random public birth.' uses a specific verb and resource, clearly distinguishing it from sibling tools like 'get_birth' (specific) and 'list_births' (list). The purpose is immediately 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?

No guidance on when to use this tool vs alternatives such as 'search_births' or 'get_birth'. The description does not mention exclusions or context, leaving the agent to infer 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?

No annotations provided, so description carries full burden. It clarifies the operation is a public read/search, but omits details on auth, rate limits, or side effects. The mention of 'fixed + extra parents' is vague.

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

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

One sentence efficiently conveys purpose and parameters with no fluff. Front-loaded with the action and resource.

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?

Covers purpose and parameters adequately for a simple search tool, but lacks output format details and the 'fixed + extra parents' concept remains unexplained. Missing output schema means agent must infer return 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?

Input schema has no descriptions (0% coverage). Description adds meaning for all three parameters: q as search text, verified for OIDC filter, limit with defaults. That's valuable beyond 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?

Clearly states the tool searches public births by child name, parent label, or parent Colony handle, distinguishing from siblings like list_births or get_birth.

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?

Describes parameters and implicit use cases (search by name/parent etc.), but does not explicitly state when to use this vs other birth tools, nor mention exclusions or 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?

No annotations provided, but description discloses key behavioral traits: operation is not immediate ('Nothing runs until triggered'), tokens are shown once and must be kept, and returns specific data. Could mention side effects or token expiry but 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?

Two sentences, front-loaded with action and key details. No wasted words, every sentence adds value.

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?

Describes return values and asynchronous behavior but omits explanations for 'public' and 'min_parents' parameters. Lacks details on token roles (owner vs participant) and output schema, though description mentions keys.

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 50% (parent and result_webhook described). The description adds context about return values but doesn't detail the meaning of 'public' or 'min_parents'. Partially compensates for schema 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 clearly states the verb 'Stage' and the resource 'agent merge' with the role 'initiator (parent #1)'. It distinguishes from siblings like join_merge by specifying it's for initiating a merge as the first parent.

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?

Provides clear context: 'Submit your OWN contribution', 'Nothing runs until triggered (admin/payment)', and 'KEEP THE TOKENS — they are shown once'. However, lacks explicit when-not-to-use or comparison to alternatives like join_merge.

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 does not disclose any behavioral traits. With no annotations, the agent receives no indication of side effects, access requirements, or whether the tool is read-only. The term 'aggregate' suggests computation but no consequences are 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?

At three words, the description is extremely concise but at the expense of completeness. It fails to include essential details about the scope, output, or context, making it under-specified rather than efficiently brief.

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 absence of an output schema and annotations, the description is the sole source of information. It is insufficient for an agent to understand what 'public stats' includes or how the response is structured, leaving a significant gap in context.

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

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

The tool has zero parameters and the input schema is empty (100% coverage). The description adds no value beyond the schema, as it does not explain what the aggregated output represents. Baseline is 4 for zero params, but reduced because the description should clarify the return 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 'Aggregate public stats' uses a verb (aggregate) and a resource (public stats), distinguishing it from sibling tools that handle specific entities like births or certificates. However, it lacks specificity about what metrics are aggregated, leaving the agent with an unclear 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions, forcing the agent to infer usage from the vague description alone.

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 discloses the return format {ok, issuer_bound, reasons, notes} and the algorithm, but does not explicitly state if the operation is read-only, auth requirements, or side effects. Moderate transparency.

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 with distinct value: function, usage, return. No fluff, front-loaded with key info.

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?

While the description covers purpose, parameters, and return format, it lacks detail on the return fields (e.g., meaning of ok and issuer_bound) and does not mention if the tool is destructive or has prerequisites. Without an output schema, more detail would be beneficial.

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%, but the description adds meaningful context: birth_id is for public births only, and the certificate object alternative. This goes beyond the schema's basic 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 clearly states the verb 'verify' and the resource 'Progenly birth certificate' with specifics about the algorithm (ed25519). It distinguishes from sibling tools like 'get_certificate' which likely retrieves without verifying.

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 explains when to use each parameter: pass a certificate object or a birth_id for a public birth. It provides clear context but does not explicitly exclude alternatives or mention 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?

Discloses key behavioral details: the token exchange step, that only id_token is passed, and that on match the contribution is marked 'colony_username_verified'. No annotations exist, so description carries full burden; it effectively explains the flow and outcome without contradictions.

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?

Description is longer but front-loaded with purpose and necessary context for a complex multi-step process. Every sentence adds value, though the token exchange instructions could be slightly tightened. Avoids 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?

Given no output schema, low schema coverage, and four required parameters, the description covers purpose, flow, and outcome but omits details on merge_id and parent_id. It is adequate for a security-sensitive tool but leaves gaps in parameter understanding, especially for new users.

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 only 25% schema description coverage, the description adds meaning for id_token ('the audience-scoped id_token returned by token exchange') but does not explain token, merge_id, or parent_id. The phrase 'needs your participant_token (or owner_token)' likely maps to token but is ambiguous. Two of four parameters remain underspecified.

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

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

Description clearly states the tool's purpose: 'Prove this contribution controls the Colony username it claims, agent-natively (no browser).' It uses a specific verb ('prove') and resource ('colony_username'), and differentiates from sibling tools like verify_certificate by its unique token exchange workflow.

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?

Provides clear preconditions: 'FIRST exchange your Colony API JWT for an id_token via RFC 8693 token exchange... then pass ONLY that id_token here.' Also mentions required participant_token/owner_token. Lacks explicit when-not-to-use or alternatives, but context is adequate.

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