Progenly

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

With no annotations, the description must carry the full burden of behavioral disclosure. It merely states 'cancel,' implying a destructive or undo action, but does not describe side effects, reversibility, owner_token semantics, or any safety considerations.

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 minimal (one phrase), which is too brief to convey necessary information. True conciseness balances brevity with completeness; here, clarity is sacrificed.

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 multiple related siblings, the description is severely incomplete. It fails to explain the tool's role in the merge lifecycle or provide parameter context, making it hard for an agent to use correctly.

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

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

Schema coverage is 0%, yet the description only mentions 'owner_token' in parentheses without explaining its meaning or relationship to merge_id. It adds no value beyond the schema, leaving both parameters unexplained.

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 'Cancel a staging intent (owner_token),' which is a verb+resource combination indicating cancellation. However, it does not define what a 'staging intent' is, leaving ambiguity. It vaguely differentiates from sibling tools like 'stage_merge' but lacks clarity on the tool's exact 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 (e.g., when to cancel vs. lock or confirm). Context signals and sibling tools suggest a merge workflow, but the description offers no usage context 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 fully disclose behavior. It mentions 'consent required' and an optional signature, but it fails to describe side effects (e.g., whether the operation is destructive or reversible), required permissions, or error states. The behavior is partially explained but lacks depth.

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

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

The description is concise, using two sentences to convey purpose and key parameter hints. It is front-loaded with the main action and required consent. However, it could be better structured with clear sections. It avoids unnecessary fluff.

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

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

Given 5 parameters, no output schema, and moderate complexity, the description is incomplete. It does not explain parameter semantics for all required fields (merge_id, parent_id, consent) or return values. Context on when to use the tool is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains the 'token' parameter (participant_token or owner_token) and mentions 'self_attestation_sig' as optional. However, it does not explain 'merge_id', 'parent_id', or 'consent' (beyond stating consent is required). With 5 parameters, this is insufficient.

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: 'Finalise your contribution (consent required).' It identifies the key action (finalizing) and resource (contribution/parent). Although it does not explicitly differentiate from siblings, the action is distinct from other tools like cancel_merge 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?

There is no guidance on when to use this tool vs. alternatives. The description mentions 'consent required' but does not explain prerequisites, exclusions, or contextual conditions. It lacks explicit when-to-use or when-not-to-use information.

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 the description bears full burden. It only says 'Get' (implies read) and 'names only' (a behavioral detail). However, it omits error behavior (e.g., if ID is invalid), whether the response includes any metadata, or if there are rate limits. For a simple get, this is insufficient.

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 with front-loaded information. Every word serves a purpose; no waste. However, it is perhaps too brief but still scores high on conciseness.

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

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

Given the tool's simplicity (1 param, no output schema, no annotations), the description covers the core action and a key constraint ('names only'). However, it lacks details on response format, possible error messages, and how 'names only' manifests in output. It is minimally complete but not fully informative.

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% (id parameter with 'Birth UUID' description). The description adds 'names only' but does not elaborate on the parameter itself. Thus, no added value beyond schema, meeting 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?

Clear verb 'Get' and resource 'birth', with specific constraints: one public birth by id and 'names only' which distinguishes from list_births (multiple) and search_births (search). The differentiation from siblings like random_birth is implied.

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

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

No explicit guidance on when to use this tool over siblings. The description is minimal; it does not mention alternative tools or conditions (e.g., 'use this when you have a specific ID, otherwise use search_births').

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 states 'Get', implying a read-only operation, but does not disclose permissions, side effects, or output 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?

The description is a single concise sentence with no fluff, but it could be more informative without sacrificing brevity.

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 having only one parameter and no output schema, the description does not explain what a 'certificate envelope' is or what the tool returns, leaving the agent with incomplete information.

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 schema parameter description. The tool description adds minimal context ('public birth's certificate envelope') beyond the schema, so 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 uses a specific verb 'Get' and resource 'public birth's certificate envelope', clearly distinguishing it from siblings like verify_certificate and 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?

No guidance on when to use this tool versus alternatives such as verify_certificate or get_birth. The description does not provide context for usage decisions.

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

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

With no annotations provided, the description bears full responsibility for behavioral context. It only mentions 'public', but does not clarify if the operation is read-only, any side effects, or failure modes.

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, focused sentence with no extraneous information, making it highly 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?

Despite having only one parameter and no output schema, the description fails to explain what a 'whole-lineage proof bundle' comprises or how the output is structured, leaving the agent underinformed.

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% with a single 'id' parameter described as 'Birth UUID'. The tool description adds context by specifying that the birth is public and about lineage, which supplements 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 verb 'Get' and the specific resource 'whole-lineage proof bundle' for a 'public birth', distinguishing it from siblings like get_birth which likely returns a single birth record.

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 this tool is for obtaining lineage proofs, but does not explicitly state when to use it over alternatives like get_birth, get_certificate, or verify_certificate.

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 description carries full burden. It mentions return values but does not clarify if the tool is destructive, requires authentication, or has side effects beyond returning tokens.

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 a single, reasonably concise sentence that states purpose and return value. No unnecessary words, but could be more structured with separate lines for clarity.

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 no annotations, the description provides basic purpose and return, but lacks completeness in usage context and parameter details. Adequate but not comprehensive.

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 only 33% (only 'parent' has a description). The description adds a brief explanation for 'parent' but does not elaborate on 'merge_id' or 'join_token', leaving their purposes unclear.

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 action ('Join a staged merge'), the resource ('staged merge'), and the mechanism ('using the join_token'). It also mentions return values ('participant_token + signing input'). This distinguishes it from sibling tools like 'stage_merge'.

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?

Description lacks explicit guidance on when to use this tool vs alternatives. It does not mention prerequisites (e.g., need a join_token from another participant) or contexts where other tools are more 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 must fully disclose behavior. It only mentions 'public' and 'names only', but lacks details on pagination mechanics, ordering, rate limits, 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?

The description is a single concise sentence, front-loaded with key information. However, it is slightly too brief, missing details that could be included without 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 the simple tool with one optional parameter and no output schema, the description omits specifics about return values (e.g., array of name strings), pagination limits, and how to navigate pages. Incomplete for a new user.

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 description adds 'paginated' which implies the page parameter's role, but does not explain page size, default page, or other nuances. Schema coverage is 0%, so more detail is needed.

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

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

The description clearly states the verb 'list', the resource 'births', and specifies 'public births (names only)' and 'paginated', distinguishing it from siblings like search_births and 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?

No guidance on when to use this tool versus alternatives like search_births or get_birth. The description does not mention prerequisites or 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 bears full responsibility for behavioral disclosure. It only states the action without details on ordering, pagination, idempotency, or any constraints, which is insufficient for an agent to understand side effects.

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 with no wasted words. It is appropriately sized for a simple tool with no 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 zero parameters and no output schema, the description is minimally complete. However, it lacks context about the scope of 'revoked certificates' (e.g., all or filtered) and does not imply ordering or behavior, leaving gaps for the agent.

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?

There are zero parameters and schema coverage is 100%, so the description adds no parameter info. Per guidelines, baseline is 4 as there is nothing to describe 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 'List revoked certificates' clearly states the verb (list) and resource (revoked certificates), distinguishing it from sibling tools like get_certificate (single) and search_births (search). It is specific and 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?

No usage guidelines are provided. The description does not indicate when to use this tool vs alternatives like get_certificate or search_births, nor any prerequisites or 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 provided, so description must disclose behavioral traits. Indicates a mutation (locking), but does not state if reversible, required permissions, or what happens if already locked or intent not ready. Incomplete 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?

Single sentence, short, but overly terse. Could be more informative while remaining concise. Lacks structure but is not verbose.

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

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

For a tool with two required params and no output schema, description lacks preconditions (what is a 'ready intent'?), error states, and return value. Insufficient for an agent to use correctly.

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

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

Schema coverage is 0%, so description should explain parameters. Only mentions owner_token in parentheses as authentication. No details on merge_id (e.g., what it represents, how to obtain it). Leaves agent guessing.

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 is to 'lock a ready intent' and specifies the effect: 'no further parents can join'. Distinguishes from siblings like cancel_merge (cancel) and join_merge (add). However, 'ready intent' is jargon not explained.

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

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

No explicit guidance on when to use vs alternatives. Mentions owner_token for authentication but does not compare to similar tools like cancel_merge or confirm_parent. Missing criteria for when locking 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?

No annotations exist, so the description carries the full burden. It mentions outputs (parents, ready flag, child) but does not disclose if it is read-only, destructive, or requires specific authorization. Behavioral traits beyond the stated outputs are missing.

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 concise sentence, front-loading the key outputs. However, it sacrifices clarity and completeness for brevity.

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 output schema and annotations, the description should explain the return value structure more thoroughly. The tool is a status check in a complex domain with many siblings, yet the description is minimal.

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%, and the description does not explain what 'token' or 'merge_id' mean. It only says 'any token for it', which is insufficient. The agent gets no semantic help beyond parameter names.

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 it provides status of a staging intent including parents, ready flag, and child, which gives a general idea. However, the term 'staging intent' and 'any token for it' are vague, and it does not clearly differentiate from siblings like get_birth or get_lineage.

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 like get_birth or get_lineage. No exclusions, prerequisites, or context provided, making it hard for the agent to decide optimally.

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 provides minimal behavioral insight. It does not disclose whether the tool is read-only, has side effects, or requires any permissions. The word 'Get' implies read-only, but it's not explicit.

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, front-loaded and free of fluff. However, it is under-specified for a tool that could benefit from a bit more context (e.g., what a 'public birth' is).

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 simplicity (no params, no output schema), a slightly richer description could improve completeness. It lacks information about the return value (e.g., a birth record ID or full details) and behavioral 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, so the description adds no param information, which is acceptable. The schema description coverage is 100% (vacuously). Baseline 4 applies.

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

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

The description clearly states the action ('Get') and the resource ('a random public birth'), distinguishing it from siblings like get_birth (specific) and list_births (all). The term 'public birth' is slightly ambiguous but understandable in context.

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. The description does not mention scenarios like needing a random sample or 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 only partially discloses behavior: it mentions 'fixed + extra parents' but does not cover pagination, sorting, error handling, rate limits, or what happens when no results are found. Significant gaps remain.

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 efficient sentences: first states purpose, second details parameters. Front-loaded, no redundancy, every sentence 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?

Lacks details on output format, error handling, rate limits, or how results are returned. Given no output schema and no annotations, the description is insufficiently complete for reliable agent 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?

Adds meaning beyond schema by explaining q searches by child name/parent label/handle, verified filters for OIDC-verified parents, and limit's default (24) and max (50). With 0% schema coverage, this is helpful and mostly clear.

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 specifies the tool searches public births by child name, parent label, or parent Colony handle, distinguishing it from sibling tools like get_birth (single retrieval) or list_births (no search). However, it could be more precise about whether q searches across all those fields or specific ones.

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

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

No explicit guidance on when to use search_births vs alternatives like get_birth, list_births, or random_birth. The description does not state prerequisites or situations where this tool is preferred.

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

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

No annotations exist, but the description discloses that tokens are shown once and must be kept, and that the merge is not executed until admin/payment. This provides useful behavioral context.

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

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

Three concise sentences with front-loaded purpose. Every sentence adds value with zero 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?

With no output schema, the description lists return values (tokens) and lifecycle. It is mostly complete but lacks clarity on the 'public' and 'min_parents' fields.

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 50%, and the description adds little beyond the schema. It does not explain the 'public' or 'min_parents' parameters, relying on defaults without clarifying their role.

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 goal: 'Stage an agent merge as the initiator (parent #1).' It uses specific verbs and distinguishes it from siblings like join_merge or cancel_merge.

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 when to use (as first step) and mentions that nothing runs until later triggers. However, it does not explicitly contrast with join_merge or mention 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 present, so description is the sole source. It only mentions 'aggregate' and 'public', implying a read operation but no details on side effects, permissions, or output 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?

Single sentence is concise but vague, not earning its place fully; it fails to provide sufficient detail for agent use.

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 and no parameters, and given the tool likely returns aggregated data, the description is too sparse to be complete.

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

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

Tool has zero parameters and 100% schema coverage, so baseline is 4. The description offers no param-specific info, but none is needed.

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

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

The description states 'Aggregate public stats', which indicates a verb and resource but lacks specificity about what stats are aggregated. It distinguishes from siblings only minimally due to the generic term 'stats'.

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 like list_births or search_births. No exclusions or context provided.

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

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

With no annotations, the description carries the full burden. It mentions the cryptographic type and return shape but does not disclose side effects (likely read-only), permission requirements, or error behaviors. The description is decent but could be more transparent.

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

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

The description is extremely concise with two sentences. The first sentence states the purpose, and the second provides usage and return format. No wasted words.

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

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

The description specifies the return structure ({ok, issuer_bound, reasons, notes}) despite lacking an output schema. It covers input modes and the core behavior. However, it omits details like error handling or field semantics, which would improve completeness.

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

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

Schema coverage is 100%, but the description adds value by clarifying that the two parameters are alternatives: either a certificate object or a birth_id for public births. This guides the agent on when to use each parameter beyond the schema's 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 tool verifies a Progenly birth certificate with a specific cryptographic type (ed25519 attestation envelope). It distinguishes itself from siblings like 'get_certificate' (retrieval vs. verification) and specifies input options and return format.

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

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

The description provides clear context on how to use the tool: pass a certificate object or a birth_id for a public birth. However, it does not explicitly state when not to use it or contrast with alternatives like 'verify_colony_handle'.

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

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

With no annotations, the description carries the full burden. It discloses key behaviors: the contribution is marked 'colony_username_verified' on a match, the raw API credential is never sent, and the token exchange endpoint is specified. It does not describe failure modes or reversibility, but the disclosed details exceed typical tool descriptions.

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 moderately long but every sentence adds value. It front-loads the purpose, then gives the token-exchange instructions and requirements. It could be tightened, but it is not wordy or redundant.

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 involves a complex OAuth token exchange and multiple required parameters. The description explains the auth flow well but leaves merge_id and parent_id undefined, which is a significant gap for a tool with no output schema and no annotations. It is not fully complete.

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

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

Schema description coverage is only 25% (only id_token has a description). The description clarifies id_token ('the audience-scoped id_token') and token ('your participant_token or owner_token'), but merge_id and parent_id are left unexplained. Since the schema is sparse and the description doesn't fully compensate, a 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: 'Prove this contribution controls the Colony username it claims.' This is a specific verb+resource combination that distinguishes it from siblings like verify_certificate, which targets a different verification type.

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 preconditions and a step-by-step flow: 'FIRST exchange your Colony API JWT for an id_token via RFC 8693 token exchange... then pass ONLY that id_token here.' It also notes the required participant_token/owner_token. However, it does not explicitly name alternatives or when-not-to-use this tool, so it falls short of a 5.

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