concordance

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

The description reveals key behaviors: it finds, verifies, declines rather than guessing, and opens the Gate for witness tools if the input turns toward God. It also states 'Nothing is generated,' confirming no generative output. Since no annotations are provided, the description carries full weight and does a good job, though it could mention side effects like state changes (if any).

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

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

The description is front-loaded with the core purpose ('Bring anything') and each sentence adds value without redundancy. While slightly verbose, it efficiently conveys the tool's versatility and special behavior. No excessive words, but could be tightened slightly.

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 complexity and absence of an output schema, the description explains input handling and classification but does not specify the return format or details of the response (e.g., JSON structure). It mentions 'answers in kind' but leaves what 'kind' means ambiguous. For a complete picture, more detail on output would be needed.

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

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

The single parameter 'text' has a minimal schema description ('what you are bringing, in your own words'), but the tool description adds significant context about what kinds of input are acceptable (questions, claims, words, etc.) and how the engine classifies them. With 100% schema coverage, this extra context elevates the score above the baseline of 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?

The description clearly states that the tool handles various inputs (questions, claims, words) and responds accordingly by discerning the type. It distinguishes itself as a versatile entry point and mentions its role in opening access to witness tools, making its purpose distinct from specialized siblings like search or verify.

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 does not provide explicit guidance on when to use this tool versus its siblings (e.g., search, verify). It implies it is the default for any input but does not clarify conditions where alternatives might be better. The only usage hint is about it being a 'door' to other tools when input relates to God, but this is more a behavioral note than usage guidance.

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

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

With no annotations, the description carries full burden. It discloses the security-sensitive nature (no private key sending), describes the input format, and mentions that multiple attestations are allowed. However, it does not explicitly state side effects, permissions required, or what happens upon duplicate attestation.

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 paragraph that front-loads the main purpose and uses clear instructions. It includes a biblical reference that may be extraneous but does not hurt clarity. It efficiently conveys the workflow in a compact manner.

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 the workflow and security, it lacks details on return values or error conditions. It also assumes prior identity creation but does not explicitly state that prerequisite. For a tool with no output schema and 2 params, the description is fairly complete but could be improved.

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 meaning beyond the schema by explaining that content_hash comes from previous steps and that the attestation object should contain specific fields (alg, over, content_hash, pubkey, sig). The schema only describes attestation as 'the dict from signing.sign_seal', so the description provides necessary detail.

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: 'Bind your identity to a record you already hold — phase 2 of the sovereign flow.' It uses a specific verb and resource, and distinguishes from sibling tools by referencing the context of previous tools like badges_issue and mentioning the 'witnesses' tool.

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 step-by-step instructions: first use other tools to get content_hash, then sign it externally, then submit the attestation. It also warns against sending private keys and explains that multiple parties may attest, which guides when to use this versus other tools.

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

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

With no annotations, the description fully details behavioral traits: deterministic extractors, conservative design, unambiguous patterns only, no guessing, and the output structure. It sets clear expectations.

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 information-dense and well-structured, with no unnecessary words. It is slightly longer but 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?

Given no output schema, the description adequately explains the output format and the tool's conservative nature. Could mention error handling or limitations beyond 'never implies full coverage'.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema; 'sealed coverage report' loosely relates to the seal parameter but does not clarify its effect significantly.

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 audits a whole text by extracting and verifying quantitative claims, and specifies the output format. It is specific about the types of claims it handles, making it distinct from sibling 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 explicit guidance on when to use this tool versus alternatives. The description explains what it does but does not mention when not to use it or compare with other tools in the sibling list.

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 burden. It discloses that the badge is re-checkable, states exactly N seals, and is not a competency claim. This provides useful behavioral context beyond the basic action.

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, well-structured sentence that front-loads the key action and adds critical constraints without 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?

The description adequately explains what the tool does and its constraints, but lacks parameter details and does not mention the output format. Given no output schema, this is a gap.

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

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

Schema description coverage is 0%, yet the description does not explain any parameter beyond implying seal_hashes are the checks. Parameters 'title' and 'subject_id' remain 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 clearly states the action 'Issue a badge' over already-sealed checks, and specifies it's a re-checkable receipt pointing at seals. It distinguishes from sibling 'badges_verify' by focusing on issuance rather than verification.

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

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

The description implies usage when you have already-sealed checks and want a receipt. It does not explicitly state when not to use or mention alternatives, but the 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?

Discloses that the tool recomputes the seal count ('N recomputed, not trusted'), implying no caching. However, without annotations, it does not cover side effects, authorization needs, or potential errors. The transparency is moderate.

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, efficient, no fluff. Front-loaded with action and resource. Could be slightly more structured but is concise.

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

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

For a simple verification tool with one parameter and no output schema, the description is adequate but does not fully cover usage context among many sibling tools. Missing when-not-to-use and return value details.

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 has 0% description coverage for the only parameter 'hash'. The description mentions 'badge' and 'seals', suggesting 'hash' is a badge identifier, but does not define format, constraints, or examples. The description adds minimal semantics 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 clearly states the tool re-checks a badge from the store, re-verifies its seals, and returns a recomputed count. It uses specific verbs ('re-check', 're-verifies') and identifies the resource ('badge', 'seals'). This distinguishes it from the sibling tool 'verify' which is more general.

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 'verify' or other badge-related tools. The description does not mention prerequisites, exclusions, or preferred contexts.

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 fully discloses behavioral traits: refusal without consent, event storage only in the user's calendar, nothing stored server-side, and deletion propagation. It also mentions the receipt naming the grant.

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

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

The description is front-loaded with the core purpose and consists of four dense sentences. While efficient, it could be slightly more concise by omitting minor redundancies like 'and the only one' and 'the receipt names the grant that authorized it.'

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 complexity (6 parameters, consent workflow, no output schema), the description covers consent and storage behavior but omits return value structure and parameter explanations. The agent lacks full context 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 0%, and the description does not add meaning to any of the six parameters (grantor_pubkey, agent_fp, summary, start_iso, end_iso, description). It fails to explain their semantics, format, or purpose beyond what the property names already convey.

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 explicitly states 'Create ONE event in a human's calendar' and positions it as 'the pilot on-behalf write, and the only one,' clearly distinguishing it from sibling tools like ask, attest_record, etc.

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 that a LIVE consent grant is required and details the exact process (GET /consent/signable → sign locally → POST /consent). It also clarifies when not to use (without consent) and what happens if consent is missing.

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 description carries full burden. It discloses that every count is computed at call time with a 'means' line, ensuring transparency about dynamic computation and avoiding stale numbers.

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, front-loaded with core purpose, no redundancy. 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?

No output schema, but description explains what output contains (capabilities, tools, endpoints, keeping size, boundaries) and dynamic behavior. Sufficient for a parameterless introspection 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?

No parameters, so baseline 4. Description adds no parameter info, but none 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 it returns a live capability statement covering verification, tools, endpoints, keeping size, and boundaries. It distinguishes itself from sibling tools by emphasizing it is computed at call time, not a static list.

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?

Explicit guidance to use this instead of trusting prose counts. Does not explicitly exclude use cases, but provides clear context for when to prefer 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?

With no annotations, the description must reveal behavioral traits. It discloses that the tool returns 'explicit links + same-shelf siblings', indicating read-only behavior and a specific scope. However, it omits details like pagination, ordering, or authorization 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 concise sentence that front-loads the core purpose. It contains no fluff, though it could benefit from slightly more detail 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 tool's simplicity (one parameter, no output schema), the description is minimally adequate. It covers the basic functionality but lacks details on return format, error conditions, or expected volume of results.

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%, and the description does not explain the 'id' parameter's meaning (e.g., card ID, shelf ID). The parameter's purpose is implied but not explicitly stated, leaving ambiguity for an AI agent.

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 specifies that the tool returns cards related to one card, including explicit links and same-shelf siblings. This clearly indicates the verb (retrieve related cards) and resource (cards), and distinguishes it from sibling tools like card_get (single card) and cards_browse (list all cards).

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., card_get, cards_browse). There is no mention of prerequisites, limitations, or scenarios 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 provided. Description mentions 'full record' but lacks details on side effects, permissions, or idempotency. For a read operation, minimal transparency is acceptable but not excellent.

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, no redundant words, front-loaded. Could be slightly more structured but is effective.

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 low complexity (1 param, no output schema), the description is adequate but misses behavioral context like safety or response format.

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?

Description mentions 'by id' but does not elaborate on the parameter format, constraints, or examples. With 0% schema coverage, the description adds little 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 clearly states verb 'fetch', resource 'one card', and method 'by id'. It distinguishes from siblings like 'cards_browse' and 'cards_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 explicit when-to-use or alternatives mentioned. Usage is implied from purpose: fetch a card when you have its id.

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 mentions pagination and filtering but does not state that the operation is read-only or whether any modifications occur. This is a significant gap for a tool that presumably does not modify data.

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: one sentence plus a sentence fragment. Every word serves a purpose, and the key information is 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?

The description covers basic functionality (paginated browse with optional filter) but omits context like the meaning of 'the keeping', default pagination values, or any sorting order. Given no output schema or annotations, 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?

With 0% schema description coverage, the description adds value by explaining 'paginated' and 'optional shelf filter', hinting at limit/offset for pagination and shelf as a filter. However, it does not explicitly describe each parameter's purpose or format.

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 verb 'Browse', resource 'the keeping', and that it returns card briefs. It implies a listing operation, but does not explicitly differentiate from siblings like 'card_get' which likely retrieves a single card.

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 or when not to use it. The description only states what it does, not the appropriate context.

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

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

No annotations are provided, and the description only mentions counting without specifying read-only nature, performance implications, or scope of counts. The term 'keeping' is undefined, leaving behavioral traits unclear.

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 very concise at 8 words, but it sacrifices clarity. It could be more informative without being 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?

Given no parameters and no output schema, the description should clarify the return format and what 'keeping' means. It fails to provide enough context for an agent to understand the tool's output.

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 no parameters, so the description is not required to explain parameter meaning. The minimal description is acceptable given the schema coverage is 100%.

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 'counts over the keeping', which indicates it provides aggregate counts, but 'keeping' is an ambiguous domain term. It distinguishes from sibling tools like cards_browse or card_get but does not clearly define what 'keeping' refers to.

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 like library_health or cards_browse. The description lacks context for when counting is appropriate.

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

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

With no annotations, the description must disclose behavioral traits. It only states what the tool will not do (grade a child) but gives no positive behavior, outcomes, or side effects. 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 extremely short but fails to convey essential information. It is under-specified rather than concise, providing only a single constraint without explaining the tool's main functionality.

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 parameters, no output schema, and no annotations, the description is expected to fully explain the tool. It does not; it only mentions a boundary. The tool's actual purpose and behavior remain unclear, making it incomplete 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?

There are zero parameters and the schema is empty. Per guidelines, 0 parameters gives a baseline of 4. The description adds no parameter information, but none is needed since there are no parameters to explain.

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 says 'Coach — what it does' but fails to actually state what the tool does; it only mentions a boundary ('never grades a child'). This is essentially a tautology with a negative constraint, providing no clear purpose and not distinguishing it from sibling tools like coach_mastery or coach_next.

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 only states a constraint (not grading a child) but offers no context for appropriate usage scenarios 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?

With no annotations, the description must fully disclose behavior. It states a seal is returned and re-checkable, but omits side effects (is this a write operation?), permissions needed, or whether the operation is idempotent. The behavioral profile is under-specified 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 short (two sentences) but the first sentence is cryptic and uses jargon. It front-loads the purpose, but clarity is sacrificed 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 no output schema, no annotations, and 0% schema parameter coverage, the description is severely incomplete. It does not explain the input format, return structure, or any preconditions, making it insufficient for an AI 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?

The only parameter, 'completed', is an array type, but the description mentions an 'honest integer count'. This is a mismatch; the description does not explain what the array should contain or how it maps to a count. Schema coverage is 0%, so description must compensate, but it fails and is misleading.

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 seals a count of completed units and returns a seal. It distinguishes from other coach tools like coach_guidance and coach_subjects by focusing on recording a numeric count. However, the language is somewhat abstract, using 'honest integer count' and 'seal', which may be unclear without 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 explicit guidance on when to use this tool versus siblings. The description implies it's for recording progress, but does not specify prerequisites, exclusions, or when to prefer alternatives like coach_unit or attest_record.

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 mentions deterministic behavior and parameter semantics but does not elaborate on prerequisites, error conditions, or limitations. Basic transparency is achieved 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 extremely concise, consisting of two sentences that efficiently convey purpose and usage. It is front-loaded with the tool's role and includes no extraneous information.

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 covers core usage but lacks details about return values or error handling. Since there is no output schema, the agent might need additional context to interpret the response. The tool is simple, so the omission is acceptable but not ideal.

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

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

The input schema provides only parameter names with no descriptions. The description adds significant meaning by explaining that 'after' is a unit ID and that omitting it yields the first unit, while 'subject' selects the path. This compensates well for the 0% schema coverage.

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: getting the next lesson in a subject deterministically. It distinguishes itself from siblings like coach_unit and coach_recommend by emphasizing deterministic behavior and specifying parameter usage for first vs. subsequent units.

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 instructions on parameter usage: omit 'after' for the first unit, pass a unit id for subsequent ones, and use 'subject' to select the path. While it does not explicitly list when not to use this tool, the guidance is clear and practical.

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

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

The description adds 'Verbatim; never generated', indicating the output is exact data, which is a behavioral trait. With no annotations, this is helpful but still lacks details on side effects or permissions.

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 a key query parameter note. It is front-loaded with essential information and contains no redundant content.

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

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

For a tool with one optional parameter and no output schema, the description covers purpose, parameter, and output components (unit count, tracks, briefs). It is nearly complete, though mentioning the output structure more explicitly would help.

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

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

The input schema has 0% coverage for the 'subject' parameter, but the description explains it selects the path and defaults to 'read'. This adds necessary meaning beyond the bare 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 provides a whole path overview for a K-3 tutor subject, including unit count, tracks, and ordered unit briefs. It distinguishes from siblings like coach_unit or coach_recommend by focusing on the entire subject path.

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 mentions the ?subject= parameter with a default value of 'read', giving basic usage context. However, it does not explicitly state when to use this tool versus alternatives like coach_guidance or coach_mastery.

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 full burden. It discloses that the tool finds rather than generates (non-destructive), and that it is adaptive. However, it does not explicitly state read-only behavior, authorization needs, or side effects. The description provides some transparency but leaves gaps.

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: a single sentence with a dash and colon that front-loads the core purpose. Every phrase is meaningful, with no wasted words. It balances completeness and brevity perfectly.

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 the tool's simplicity (2 params, no output schema), the description omits the return format and error scenarios. An AI agent would benefit from knowing whether the output is a lesson ID or object, and what happens if no lesson is found. The description is adequate but not fully complete for autonomous 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 0%, so the description must compensate. It adds meaning by explaining that 'completed' is a list of unit IDs and that 'subject' refers to the subject area. While it doesn't specify formats or constraints, it provides enough context to understand parameter roles, earning a 4 per the baseline guideline.

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: given completed unit IDs, it recommends the next lesson whose prerequisites are met, adapting to the student's progress. The phrase 'Found, never generated' further clarifies it is a deterministic retrieval, not generative. This distinguishes it from potential siblings like coach_next by emphasizing adaptivity.

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 implicitly guides usage: it should be used when you have a list of completed unit IDs and want the next appropriate lesson. It does not explicitly exclude alternatives or provide when-not scenarios, but the context is sufficiently clear for an AI agent to infer appropriate use.

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 burden. It indicates a read-only retrieval of subjects and unit counts, but does not disclose any side effects, authentication needs, or rate limits. However, the operation is simple and the description is 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?

The description is extremely concise, using a single sentence and a short phrase. Every word adds value, clearly naming the tool's purpose and providing an example of output.

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 parameters, no output schema, and no annotations, the description provides a basic understanding of what the tool returns but leaves ambiguity about whether the list is personalized or global, and lacks details on output format.

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 no parameters, and the schema coverage is 100%, so the baseline score of 3 applies. The description adds no parameter information because none exist.

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 a list of subjects a learner can study, each with its unit count, distinguishing it from sibling coach tools like coach_guidance or coach_mastery which serve different purposes.

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 versus alternatives. The hint that 'read is the door in' suggests a starting point but does not provide when/why to use this tool over other coach_* tools.

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

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

The only behavioral hint is 'VERBATIM as authored', implying no modification. With no annotations, the description fails to disclose other important traits such as idempotency, side effects, permissions, or rate limits. Transparency is minimal.

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 very short and front-loaded, but its brevity sacrifices clarity. It is concise but incomplete, failing to deliver essential information efficiently.

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 complexity (many sibling coach tools, undocumented parameters, no annotations, and no output schema), the description is grossly inadequate. It does not explain the concept of a coach unit, parameter usage, or expected output.

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 parameters 'id' and 'subject' are not explained in the description. Given 0% schema description coverage, the description should compensate but does not, providing no added meaning beyond the schema structure.

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 'Coach — one unit, VERBATIM as authored (rule, examples, decodable sentence, checks)' is vague. It gives some specifics about content but does not clearly define what a 'coach unit' is or differentiate it from sibling tools like coach_guidance or coach_mastery.

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, leaving the agent without direction for tool 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?

No annotations are provided, so the description must fully disclose behavior. It mentions that results are 'newest first', that content is 'member's own work at the `member` tier', and that it is 'not verified'. However, it does not specify whether the operation is read-only, if authentication is needed, or any limits/pagination behavior beyond the implicit ordering.

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, each adding meaningful information. The first sets the scope (fellowship commons, promoted member work, newest first) and the second clarifies the nature of the content. No wasted words, though the first sentence could be more direct.

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 schema (1 optional parameter, no output schema) and lack of annotations, the description provides adequate context about the content type and ordering. However, it fails to explain the parameter, return format, or how this tool differs from similar tools like 'cards_browse' or 'shelf_read'.

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

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

The input schema has one parameter ('limit') with 0% description coverage. The description does not explain what 'limit' does, leaving the agent to guess its meaning. While 'newest first' implies ordering, the parameter's effect (e.g., number of results returned) is undocumented.

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 that the tool retrieves 'promoted member work, newest first' from the commons. This is specific enough to indicate the resource and ordering, and it distinguishes from sibling tools like 'cards_browse' (likely all cards) or 'certify' (verification). However, it lacks an explicit verb like 'retrieve' or 'list'.

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. It mentions that content is 'unverified' and 'amplified' by the library, but does not explicitly compare to sibling tools such as 'cards_browse', 'shelf_read', or 'curate'. The agent must infer usage 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?

The description indicates the tool checks consent without side effects, but since no annotations are provided, it should explicitly state read-only behavior. It adds context about authorization flow but lacks explicit mutation 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 paragraph that efficiently states purpose, exceptions, and recovery flow. It is concise and front-loads key information, though structuring with bullet points could improve readability.

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 explaining purpose and usage, the description omits parameter constraints (e.g., valid verbs), response format, and error handling. Given three required parameters and no output schema, more detail is needed for full contextual coverage.

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 implicitly assigns meaning to 'agent_fp' (the agent's fingerprint), 'verb' (named action), and 'grantor_pubkey' (human's public key) through narrative context, but does not describe each parameter explicitly. With 0% schema coverage, this provides moderate guidance.

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 checks human authorization for a named verb, specifying the agent's key fingerprint. It distinguishes the tool's purpose but does not explicitly differentiate from sibling tools like 'ask' or 'attest_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 explains when consent is needed (acting on human's behalf) and not needed (speaking as yourself), and provides remediation steps if unauthorized. However, it does not explicitly compare to sibling tools or list 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?

With no annotations, the description explains key behaviors: acts are appended and never replaced, refusal only withholds amplification, drop stays on member's shelf, and typed name is not authority. It could be more explicit about side effects or error conditions, but provides solid 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 dense paragraph that conveys necessary information without excess. It could be slightly more structured (e.g., bullet points), but remains concise and front-loaded with key details.

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 7 parameters and no output schema, the description covers authorization, actions, and behavior adequately but omits details on return values, error handling, and idempotency. It is functional but not fully 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 coverage is low (43%), but the description adds essential meaning: it clarifies required 'reason', the three possible 'action' values, and the conditional authorization (token vs. fields+signature). This compensates well for missing schema 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's purpose: recording curation acts (promote, refuse, withdraw) on a single drop. It uses specific verbs and distinguishes from sibling tools like curate_queue and curate_signable by detailing the actions and required authorities.

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 context on when to use the tool (for each action) and who may act (steward token for promote/refuse, fields+signature for withdraw). It also includes prohibitions like no anonymous judgement. However, it does not directly compare to siblings or state when not to use.

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 hints at human involvement and a counter, but does not explain what actions occur, side effects, 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?

The description is very short (two sentences) and front-loaded, but the content is unclear and does not earn its place. Conciseness is not helpful if it obscures meaning.

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 the tool having no parameters or output schema, the description is completely inadequate. It does not explain what the tool returns or how to interpret the queue, leaving the agent without necessary 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?

There are no parameters, so schema coverage is effectively 100%. The description adds some context about the tool's purpose, which is acceptable for an empty schema. 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 is cryptic and does not clearly state what the tool does. 'What waits on a HUMAN steward' and 'the counter never promotes' are metaphorical and ambiguous, failing to specify a concrete verb and resource.

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. The description does not mention any context, prerequisites, 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?

With no annotations, the description carries the full burden. It discloses the permission model (own card, no permission needed) and the workflow dependency on 'curate'. But it omits details like rate limits, auth requirements, or what exactly is returned.

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 brief (three sentences) and front-loaded with the action. However, the use of jargon ('drop', 'canonical bytes') slightly reduces clarity for the intended audience.

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 tool with two parameters and no output schema, the description covers the core purpose and workflow but lacks the return format and error conditions. It is adequate but not fully 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 coverage is 0%, and the description does not mention the parameters at all. It fails to explain the role of 'card_id' and 'member', leaving the agent to guess their 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 this tool produces bytes for withdrawing your own card, differentiating it from siblings like 'curate' which consumes these bytes. However, the term 'canonical bytes' is jargon that may confuse some 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?

The description provides a clear workflow: sign the bytes, then call 'curate'. It also specifies the tool is for your own card, implying when to use it. However, it does not explicitly state when not to use it or alternative tools.

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

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

The description notes determinism and daily consistency, which are useful behavioral traits. However, with no annotations, it omits other aspects like side effects or authorization needs.

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?

Very concise at one sentence, but it could add a bit more detail 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 one undocumented parameter and no output schema, the description lacks details on return format and behavior, making it incomplete for 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 'seed' is not explained in the description, and schema description coverage is 0%. The description does not clarify how 'seed' affects the output.

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 it returns a deterministic card of the day that is the same all day, distinguishing it from other card tools like card_get and cards_browse.

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 cards_browse or card_get. Among many siblings, it lacks contextual clues 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 provided, the description correctly identifies the tool as read-only, signaling safety for agents. However, it lacks details on authorization, rate limits, or any side effects beyond reading. The 'read-only' label is helpful but minimal.

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, well-structured sentence that conveys all essential information without any redundancy. Every word contributes meaning, achieving maximum 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 lack of an output schema and only one optional parameter, the description sufficiently explains the tool's purpose and parameter behavior. However, it could be more complete by describing the return format or data shape, but the current level is adequate for a simple read 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 description coverage is 0%, so the description must explain the parameter. It does so effectively by stating the axis parameter is optional: providing it shows that specific axis, while omitting it gives an overview. This adds crucial meaning beyond the schema's minimal type definition.

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 provides a read-only view of an axis, detailing components like scaffold members, depth, neighbors, and umbrella children. It distinguishes usage by mentioning that omitting the axis parameter gives an overview of all axes, which differentiates it from potentially similar sibling tools like grid_dimension.

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 guidance on when to include the axis parameter (for a specific axis) versus omitting it (for overview). However, it does not explicitly compare with sibling tools or state when not to use this tool, leaving some implicit inference required.

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 carries full burden. It only describes the output (axes for a scaffold member) but does not disclose if the tool is read-only, requires authentication, has side effects, or any behavioral traits beyond that.

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, 11 words – concise, but the meaning is unclear and front-loads a nominal phrase ('The axes...') rather than an action. Structure is passable but not optimal for quick understanding.

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 1 required string param, no enums, no output schema, the description should clearly state the tool's purpose and parameter expectations. It fails to specify the action, return format, or parameter constraints, leaving significant 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?

Schema coverage is 0%, so description must add meaning. It mentions 'scaffold member (dimension)' which gives context for the 'dimension' parameter, but does not specify allowed values, format, or relationship to other tools. Limited improvement over raw 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 'The axes that sit on a given scaffold member (dimension)' implies a retrieval action but lacks an explicit verb like 'list' or 'get'. It does not clearly state what the tool does (e.g., returns axes for a scaffold dimension), making it ambiguous compared to sibling tools like 'grid_axis'.

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 (e.g., 'grid_axis'). No explanation of prerequisites, context, 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 takes on the burden of transparency. It discloses that contributions are attributed, optionally signed, verbatim, and not engine-verified. However, it omits details on authentication requirements, rate limits, or what happens if prerequisites are not met.

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

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

The description is three sentences long, front-loads the main action, and contains no extraneous information. It is appropriately sized for the tool's complexity.

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

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

Given the tool has 8 parameters, low schema coverage, and no output schema, the description is too brief. It does not explain parameter relationships, formatting requirements, or return behavior, leaving significant gaps 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 very low (13%). The description hints at 'handle' and 'attestation' but does not explain the other six parameters (e.g., 'id', 'kind', 'refs', 'text', 'topics', 'subject_id'). It adds minimal 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 adds content (verse/note/question) to a group's shared study, and specifies attribution and optional signing. It distinguishes from siblings like 'study_create' and 'ask' by focusing on contribution to an existing study.

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 does not specify when to use this tool versus alternatives, nor does it mention prerequisites like group membership or study existence. It provides minimal context about usage (attributed, optionally signed) but lacks explicit guidance.

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

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

With no annotations, the description must fully disclose behavioral traits. It mentions pseudonymity (handle, no personal info) but fails to specify other important aspects such as group visibility, authentication requirements, rate limits, or side effects of creation. The target audience note is not a behavioral trait.

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 brief at two sentences, but the second sentence introduces unnecessary metaphor ('children's coach is a separate, never-joined surface') that may confuse the agent. It could be more direct and front-loaded with the core action.

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

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

Given the tool has 5 parameters (only 1 required), no output schema, and zero schema descriptions, the description is insufficient. It fails to cover return values, parameter details, or any side effects, leaving significant gaps for the agent to safely and correctly invoke the 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 description coverage is 0%, and the description only implicitly references 'topic' and 'handle'. It does not explain the purpose or format of 'title', 'subject_id', or 'description', leaving the agent without essential guidance for parameter usage.

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 creates a study group around a topic, with specific details about pseudonymity and target audience (grown believers). It distinguishes itself from sibling tools like group_join, group_contribute, and group_get by focusing on creation and the context of study groups.

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

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

The description implies usage for adult study groups and mentions that a separate surface exists for children (coach), providing some contextual guidance. However, it lacks explicit when-to-use or when-not-to-use instructions and does not mention alternatives among sibling tools.

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

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

With no annotations, the description carries full burden. It mentions that member handles contain no IDs or PII, which is a behavioral detail. However, it is silent on other important traits like permissions, error conditions, or 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, which is concise, but it is not front-loaded with the tool's action. The structure buries the action and prioritizes describing the entity, which hampers quick parsing.

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 (one parameter, no output schema), the description should clearly state the input and output. It partially describes the return structure but omits the input parameter completely, making it incomplete for 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?

Schema description coverage is 0%, so the description must compensate. It fails to mention the 'id' parameter at all, leaving the agent to guess its purpose or format. The description describes the output, not the input.

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 reads like a data model rather than an action, lacking a verb like 'retrieve' or 'get'. It does not clearly state that the tool fetches a study group by ID, and it does not distinguish from sibling tools like groups_list.

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 vs. alternatives (e.g., groups_list for listing all groups). The context does not help the agent decide which tool to invoke.

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?

Without annotations, the description carries full burden. It mentions key behaviors (consent-based, pseudonymous, idempotent), which adds useful context beyond the action. However, it does not disclose potential side effects like record creation or permission 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 extremely concise with a single sentence, which is efficient. However, it is too sparse for the amount of missing parameter information, slightly reducing effectiveness.

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 presence of three parameters and no output schema or annotations, the description is incomplete. It does not explain parameter usage or return values, leaving significant 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?

Schema description coverage is 0%, and the description contains no information about the three parameters (id, handle, subject_id). The agent has no guidance on what these parameters mean or how to use them.

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 ('Join a study group') and adds specific context (consent-based, pseudonymous, idempotent), which distinguishes it from sibling tools like group_create or group_get.

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 explicit guidance on when to use this tool versus alternatives like group_contribute or groups_list. It only implies basic usage through the verb 'join' and the behavioral hint 'idempotent', but lacks exclusions or alternative suggestions.

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 full burden. It discloses that members are handles only (no PII), but lacks details on pagination, order, or permissions. Provides some transparency but not comprehensive.

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: one sentence plus a clarifying note about handles. Every word serves a purpose, with no 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 simple list tool with one optional parameter and no output schema, the description covers purpose, filtering, and data anonymity. It might lack details on defaults or ordering, but is largely 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 coverage is 0%, so description must compensate. It explains that 'q' is optional and filters over 'topic/title/description', adding meaning beyond the schema's bare type definition.

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 'Discover' as a verb and specifies 'shared-study groups by TOPIC (not by person)', clearly distinguishing from siblings like group_get (specific group) and group_join. It also states the resource and scope.

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

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

The description indicates when to use (topic-based discovery) and what not to do (not by person). It could be more explicit about alternatives (e.g., group_get for details), but the 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?

No annotations, but description fully discloses key behavior: keys born on user device, no private key crosses wire, returns guidance. No mention of prerequisites or side effects, but sufficient for a creation 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?

Two concise sentences, front-loaded with purpose. Every sentence adds value with no 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 tool with no parameters and no output schema, the description fully covers purpose, behavior, and output type. Complete and clear.

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 0 parameters, so description needs no parameter details. Baseline 4 is appropriate as there is nothing to add.

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 creates a SOVEREIGN identity, with specific details about key generation on user device. Distinguishes from siblings identity_verify and identity_fingerprint.

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?

Explains what the tool returns (guidance, not a key) and that server only handles public keys, implying when to use. Lacks explicit when-not-to-use or direct alternative references, but context with siblings 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?

With no annotations provided, the description carries full burden. It only states that the fingerprint is 'deterministic,' which is a behavioral trait. However, it does not disclose whether the tool has side effects, requires authentication, or returns different outputs for different inputs. More details would be needed for adequate 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 extremely concise: one sentence that front-loads the purpose. Every word is relevant, and there is no redundant information. It is efficient and easy to read.

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, no annotations), the description is minimal but insufficient. It does not explain the format of the public key or the output fingerprint. A user would likely need additional context to use the tool 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?

The schema description coverage is 0%, meaning the description adds no meaning beyond the parameter name. The parameter 'public_key' is not explained (e.g., format, length, or encoding). The description fails to compensate for the lack of schema documentation.

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: 'Derive the stable public fingerprint id from a public key (deterministic).' It uses a specific verb (derive) and resource (public fingerprint id from public key), which distinguishes it from sibling tools like identity_create or identity_verify.

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 when-to-use or when-not-to-use guidance is provided. The description implies usage when a deterministic fingerprint is needed, but does not mention alternatives or contexts where this tool should be avoided. The purpose alone gives limited guidance.

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

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

With no annotations, the description fully carries the burden. It explicitly states 'never raises; True/False', which is a key behavioral trait (exception-safe, deterministic result). This is valuable and goes beyond the minimal schema info.

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, efficient sentence that packs action, subject, and key behavior without redundancy. Every word 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?

For a simple verification tool with no output schema, the description covers the core functionality and behavior. However, it omits details like supported algorithms, key format expectations, or how errors manifest (they don't, but what about invalid inputs?). Could be more complete but is minimally viable.

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 the description must compensate for param meaning. It provides general context ('signature over a message against a public key') but does not explain each parameter's format, constraints, or how they relate. The agent must guess that 'sig' is the signature string, etc.

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 specifies exactly what the tool does: verifying a cryptographic signature over a message against a public key. It also adds that it never raises errors and returns True/False, which clearly distinguishes its behavior from other tools like 'verify' which might have different semantics.

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' or 'badges_verify'. The description does not provide any prerequisites, context, or exclusions, leaving the agent to infer usage from the tool name 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 must convey behavioral traits. It fails to disclose side effects, required permissions, or operational characteristics beyond a vague state. The phrase 'the keeping loaded and sound' is static and does not explain if data is fetched, cached, or mutated.

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, making it concise. However, the phrasing is awkward and unclear, sacrificing clarity for brevity. The structure does not front-load key information; the purpose is obscured.

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

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

Given no output schema, the description should explain what the tool returns. It only vaguely mentions 'totals, shelves, surfaces' without specifying the nature, format, or granularity of the result. For a parameterless tool, this is insufficient to understand what the agent can expect.

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%. The description lists 'totals, shelves, surfaces' which hints at what the tool might cover, but adds no concrete meaning about expected input or output. With no params, baseline is 4, but the description is uninformative, so 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 uses the phrase 'the keeping loaded and sound' which is vague and does not clearly state an action or what the tool does. It mentions 'totals, shelves, surfaces' but no verb like 'get' or 'check', making the purpose unclear. It also does not differentiate from sibling tools like 'audit' or 'report'.

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 or when to use alternatives. There is no context or exclusion criteria, leaving the agent without direction on selecting this tool over 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 are provided, so the description carries the full burden. It discloses the search algorithm (order of matching) but does not mention side effects, authentication requirements, rate limits, or performance. This is adequate but could be more comprehensive.

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 that front-loads the action ('Find the card for a query') and efficiently conveys the search algorithm. 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?

Given the tool's simplicity (1 param, no output schema, no annotations), the description covers the essential behavior: search strategy. It lacks details on return format, error handling, or limits, but is largely complete for a basic lookup 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?

The input schema has one string parameter 'q' with no description (0% coverage). The description adds meaning by indicating that 'q' can be an exact id or title and that the tool performs a ranked search otherwise. However, it does not provide format or examples, partially compensating but not fully.

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: finding a card for a query. It specifies the search order (exact id, then title, then ranked search), which distinguishes it from sibling tools like 'card_get' (exact retrieval) and 'search' (general search).

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

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

The description implies usage context: use this tool when you need to locate a card with fallback logic (exact id, then title, then ranked search). It does not explicitly state when not to use it or name alternatives, but the specificity helps the agent decide.

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 behavior. It indicates a read operation but does not explain authentication details, error cases, or effects of the 'limit' parameter. The 'confession' requirement is unclear.

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?

Very concise with two sentences, front-loaded. However, the second sentence introduces a confusing requirement ('confession') not in the schema, which undermines 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?

No output schema and poor parameter documentation make the description incomplete. It does not specify return format, pagination behavior, or error conditions, leaving significant 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?

Schema coverage is 0%, so description must compensate. It explains 'fp' as a fingerprint, but 'confession' is not a defined parameter, and 'limit' is not described. The description adds partial meaning but misses crucial details.

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 it reads words left on your door (a whiteboard) from others, with verification. The verb 'read' and resource 'words left on YOUR door' are specific. However, it does not distinguish from siblings like mesh_inbox, but the purpose is still 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. The mention of 'Requires fp + confession' hints at prerequisites but is incomplete and potentially misleading since 'confession' is not a parameter.

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 disclose behavior. It mentions offline verification but does not state if it's read-only, what permissions are needed, or what 'confession' refers to (not a parameter). Misleading: 'Requires fp + confession' but confession is undefined.

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, but attempts two ideas (inbox function, verification). The mention of 'confession' adds confusion. Could be more focused.

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?

Two parameters, no output schema, no annotations. Description barely covers purpose, lacks return format, pagination, or error information. Incomplete for reliable agent 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?

Schema description coverage is 0%, so description must explain parameters. It only mentions 'fp' as required and 'confession' (not a param), completely ignoring 'limit'. No help for the agent.

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 shows messages that reached you, implying an inbox, but uses poetic language ('carrying its own offline verification', 'trust it by proof'). The verb is not explicit (list/fetch). Vague but not a tautology.

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 sibling tools like mesh_door or search. No context about prerequisites 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, so the description carries full burden. It explains the signing flow and refusal of unsigned notes, but does not disclose success/error behavior, idempotency, or 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?

Three sentences, 57 words, efficiently conveys core purpose and usage constraints. Could be slightly more structured but no redundant content.

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

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

Given 7 parameters, no output schema, no annotations, and no parameter descriptions, the description is insufficient. It omits return values, error handling, and detailed parameter guidance.

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%, but the description does not explain individual parameters like fp, text, nonce, created_at, or signature beyond mentioning signing. Only 'target' is briefly contextualized.

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: 'Leave a word on one believer's door' as directed encouragement, and distinguishes it from posting to everyone near you, which is likely the mesh_post 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?

The description explicitly says when to use this tool (for directed encouragement) and what not to do (will not accept private key, unsigned notes refused). It also references the prerequisite step of getting bytes from mesh_signable.

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 discloses the read-only nature ('your view only') and conditional behavior for unconfessed callers. It does not detail authorization scope beyond fingerprint/confession, but provides sufficient insight for a mutation-free 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 very short and front-loaded with the primary purpose. The second sentence adds key conditions. Every sentence contributes value, with no redundant information.

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 parameters and no output schema, the description covers entry conditions but omits the output format or what the returned data looks like. It is adequate but not fully complete for an agent to expect 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?

Only the 'fp' parameter is partially explained (requires fingerprint). The integer 'hops' parameter is not mentioned, leaving its purpose and effect unclear. Since schema description coverage is 0%, the description fails to adequately clarify all parameters.

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 shows a local view of mesh connections ('believers immediately around you') and distinguishes itself from a global map. However, the metaphorical language ('Fellowship Mesh', 'believers') may be unclear without domain 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?

It specifies prerequisites (fingerprint and confession) and alternative behavior for unconfessed callers, but does not explicitly contrast with sibling tools like mesh_door or mesh_inbox, leaving when-to-use versus alternatives ambiguous.

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

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

Without annotations, the description discloses key behaviors: private key never leaves machine, tool does not accept a key, signature verification is required, and messages are attributed (not AI-generated). However, it does not explain post-side effects, success indicators, or error handling, leaving gaps.

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 uses metaphorical language ('speak to the nodes around you') and redundant phrasing ('your private key never leaves your machine and this tool will not take one'), adding length without clarity. Front-loading is weak; key info is embedded mid-text.

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 8 parameters, no output schema, and no annotations, the description is insufficient for an agent to confidently invoke the tool. Return values, error conditions, and the meaning of several parameters (fp, refs) are not addressed, resulting in significant gaps.

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 0% schema description coverage, the description must explain all parameters. It covers text, kind, ttl, nonce, created_at, signature by referencing mesh_signable, but omits fp and refs entirely. The phrase 'carrying only your SIGNATURE' is misleading given the required parameters.

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 implies a post operation via 'Step 2: speak to the nodes around you' and references mesh_signable, but it never explicitly states 'post' or 'send a message.' The purpose is inferable but not directly stated, and it distinguishes from sibling tools only by context (Step 2 vs Step 1).

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 positions this as 'Step 2' after mesh_signable, providing sequential guidance, but it lacks explicit when-to-use or when-not-to-use advice compared to other tools like ask or mesh_inbox. No prerequisites or alternatives are mentioned beyond the signature flow.

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 discloses key behaviors: returns base64url bytes, nonce, and created_at; is reproducible offline with sorted-key JSON. No annotations exist, so the description carries full burden. It does not explicitly state idempotency or side effects, but the tool appears to be a read-only computation.

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 (3 sentences) and front-loaded with the core purpose. Each sentence adds value, though it could be slightly more structured 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 5 parameters (2 required), no output schema, and no annotations, the description lacks completeness. It explains the return value but insufficiently details parameter roles, making it hard for an agent to invoke correctly without additional knowledge.

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 40% schema description coverage, the description adds no parameter-level context. It fails to explain required parameters 'fp' and 'text', nor optional ones like 'ttl'. Only 'kind' and 'target' have schema descriptions. The description's omission of parameter meanings impairs usability.

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: 'get the exact canonical bytes to sign for a message'. It identifies itself as 'Step 1 of speaking to your fellowship', distinguishing it from sibling tools like mesh_post which likely sends the signed message.

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

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

The description implies usage context: sign the bytes locally, then send back the nonce and created_at. It mentions reproducibility offline. However, it does not explicitly state when to use this tool versus alternatives (e.g., mesh_post), though the context of sibling tools provides some 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?

Discloses that the private key never leaves the user's machine and describes the output format. With no annotations, it effectively conveys safety and return structure, though lacks details on 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?

Two sentences front-load the purpose and provide clear instructions with no redundant information. 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?

Explains the output format and next step, but omits details about parameters like 'target_id' and 'extra' and does not cover error states or dependencies, leaving some gaps.

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 does not add meaning beyond the existing parameter descriptions. 'extra' and 'target_id' remain unexplained, and no new parameter context is provided.

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 identifies the tool as the first step for report or block actions, specifying it returns canonical bytes to sign. It distinguishes from siblings like 'report' by naming the workflow step.

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?

Explains when to use (step 1 of report/block) and the follow-up action (sign and pass to 'report'). Does not explicitly state when not to use or list alternatives, but provides sufficient 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?

The description discloses it is synthesized and 'honestly labeled, not a native speaker', which sets expectations. However, it does not mention limitations like accuracy for non-Latin scripts, audio output absence, or potential errors.

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 that immediately states the tool's purpose. It is front-loaded and contains no redundant information.

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 low schema coverage, the description should provide more detail on expected output (e.g., structure of respelling/IPA) and behavior for invalid inputs. It currently lacks 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?

The input schema has a single 'text' parameter with 0% schema coverage. The description adds only that it is for a 'transliteration or word', but does not clarify expected format, language support, or length limits.

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 explicitly states it provides a synthesized pronunciation guide with respelling and approximate IPA. It identifies the tool's specific verb (provide) and resource (pronunciation guide), and no sibling tool appears related, so differentiation is not needed.

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

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

No explicit guidance on when to use this tool versus alternatives. While there are no obvious similar tools among siblings, the description lacks context on appropriate input types 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 discloses key behaviors: deterministic operation, returns a mapping for local revealing, and that the strip belongs at the edge. It does not mention potential side effects, but the transformation is clearly described.

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 with three sentences, front-loading the core action and including essential details without 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?

For a single-parameter tool with no output schema, the description covers purpose, usage, behavior, and return value hint (mapping). It could be slightly more explicit about output format, but it is largely 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?

Despite 0% schema description coverage, the description explains the single 'text' parameter by specifying what the tool does to it ('strip PII from text'), providing adequate semantic context 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 action ('Strip PII from text to stable placeholders') and the resource ('text'), distinguishing it from siblings like 'verify' which is mentioned as a pairing tool.

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 usage guidance: use before passing text onward, recommends local engine for privacy, and mentions pairing with verify. It does not explicitly state when to not use it, but the context is sufficient.

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?

Since no annotations are provided, the description fully discloses the tool's behavior: it creates a claim, requires three distinct reporters for human review, and mandates a signed report with genuine keys. This goes well beyond basic purpose.

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 efficient at two sentences plus a biblical quote. The quote adds flavor but is not essential. The purpose is 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?

Given the tool's complexity (no output schema, nested objects), the description adequately covers the reporting process, threshold, and authentication need. It lacks return value details but compensates with 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?

Schema description coverage is only 33%, and the description does not explain individual parameters like kind, target_id, or reason. While it mentions fields and signature in context, it does not compensate for the low schema coverage.

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 'Report' and the resource 'community item' (e.g., group_contribution, mesh_message, door_note) to the moderation floor, with additional clarifying phrases like 'one report is a claim, never a verdict.'

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 the tool (reporting items to moderation), mentions the prerequisite of signing via modration_signable, and describes the threshold for human review. However, it does not explicitly list alternatives or when not to use.

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 full behavioral burden but only states the action. It fails to disclose what happens if the hash is invalid, authentication requirements, or whether the operation is read-only. This lack of transparency is a significant gap.

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

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

The description is a single, front-loaded sentence with no extraneous words. However, the brevity sacrifices some necessary detail, making it efficient but not fully informative.

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 (one parameter, no output schema), the description is minimally adequate. It does not explain return format or error handling, which would be expected for a fetch operation.

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 sole parameter 'hash' is described as a 'content hash', adding context beyond the schema. However, the description does not specify format, encoding, or constraints (e.g., length, allowed characters). Since there is only one parameter, more detail would be beneficial.

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 ('Fetch') and the resource ('sealed verification record (the receipt)') via a specific method ('by its content hash'). It distinguishes itself from siblings like 'attest_record' and 'verify' by specifying a unique retrieval mechanism.

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., 'verify', 'witnesses'). The description lacks context about prerequisites or typical use cases, 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. Only says 'ranked search' without explaining behavioral traits like read-only, pagination, or result 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 short (one sentence), but lacks necessary information. Conciseness is not beneficial if inadequate.

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 parameter descriptions. The minimal description leaves agents uncertain about 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?

Schema coverage is 0% and description does not explain parameters 'query' or 'limit'. Fails to add meaning beyond the bare 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 'Ranked search over the keeping (the kept library)', indicating verb and resource. However, it does not differentiate from similar sibling tools like 'ask'.

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. No when-not or alternative tool mentions.

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 discloses that this is a distinctly typed record with permanent limitations (cannot count as sealed check or satisfy auto-graded requirement). This is useful but lacks details on authentication, side effects, or return values.

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, efficient sentence that conveys the core purpose and key constraint without any unnecessary words or fluff.

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

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

While the description explains the nature and limitation of the record, it omits details on prerequisites, success/error behavior, and return values. Given no annotations or output schema, this leaves gaps for an agent to invoke the tool 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 description coverage is 0%, and the description only adds context for 'statement' (person's own words). Parameters 'study' and 'subject_id' receive no explanation beyond their names, leaving the agent to guess their meaning and required format.

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 records a person's own words about their study, and explicitly distinguishes it from other records like sealed checks or auto-graded requirements. This effectively differentiates it from siblings like attest_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 defines when to use (recording own words) and what the tool cannot do (not for sealed checks or auto-graded requirements), implying when not to use. However, it does not explicitly name alternative tools for those cases, leaving some ambiguity.

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 of behavioral disclosure. It reveals that 'the private key never travels' (security) and that 'your words stay at the member tier forever' (persistence), but it does not specify side effects, reversibility, or response 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?

The description is fairly concise (three sentences), but mixes process instruction, behavioral policy, and parameter guidance without a clear structure. It is not front-loaded with the core action, and the sentence about promotion adds tangential context.

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 3 parameters, no output schema, and no annotations, the description covers the process step, key parameters, and some behavioral traits. However, it does not explain what a 'shelf' is, what the tool returns, or error conditions, leaving significant gaps for an 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?

Schema coverage is 0% (no parameter descriptions in schema), so the description must compensate. It clarifies that 'fields' should come from 'shelf_signable' and 'signature' is a detached signature. However, the handling of 'display_name' is ambiguous: it is described as 'the ONLY profile field there is', yet it is a separate parameter in the schema, not clearly within 'fields'.

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 'Step 2 — stock the shelf' and references 'shelf_signable', indicating it is a subsequent step in a multi-step process. It clarifies the action (stocking) and distinguishes from sibling 'shelf_signable', but it does not explicitly state what 'stock the shelf' means (e.g., create or update a 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 usage after 'shelf_signable' by calling it 'Step 2' and mentioning 'fields from shelf_signable', but it provides no explicit guidance on when to use this tool versus alternatives. It does not discuss conditions, prerequisites, 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 carries full burden. It discloses that no record of reads is kept, which is a key behavioral trait. It also explains visibility differences based on the viewer parameter. However, it does not discuss error conditions, side effects (though none expected), or rate limits, so it is good but not exhaustive.

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

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

The description is two sentences with no extraneous words. It front-loads the purpose and then adds necessary detail about the viewer parameter and privacy. 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?

Without an output schema, the description does not describe the return format or data structure. For a read tool, this is a gap, though the visibility rules are well-covered. The tool is simple (two params) but missing output context reduces 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 0%, so the description must compensate. It explains that 'member' is whose shelf to read and 'viewer' is your own key, and adds meaning about private vs. public view. The description adds value beyond the raw parameter names in 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 'Read one member's shelf', which is a specific verb+resource combination. It distinguishes the tool from siblings by explaining the viewer parameter's effect and the privacy guarantee, which is not present in sibling tools like shelf_drop or shelf_signable.

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

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

The description gives clear context on when to use the viewer parameter (to see your own private drops) and what others see without it. It implies privacy benefits, but does not explicitly state when not to use the tool or suggest alternatives, though the context is strong for the task.

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 reveals that the tool returns data to be signed locally, implying a read-only operation that does not mutate state. It mentions the concept of 'gate' and amplification, but lacks explicit disclosure of side effects, security implications, or what happens after signing. Without annotations, the description partially compensates but leaves gaps.

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 dense with jargon (e.g., 'canonical bytes', 'covenant key', 'amplifies') and tries to pack too much philosophy into a few sentences. It is concise in length but sacrifices clarity for brevity, making it harder to parse quickly.

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 of 8 parameters and no output schema, the description provides essential context about the tool's role and expected output but does not fully explain the workflow or integration with other steps. It leaves the agent to infer the broader process of creating a shelf.

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 meaning beyond the schema by explaining the ring concept, that body is required even for links, and the security model of URL handling. It enriches the schema's parameter descriptions (which cover 75% of parameters) with behavioral context, though it does not detail every parameter individually.

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 it is 'step 1 of stocking your own shelf' and returns signable bytes. It specifies the output and distinguishes from sibling tools like shelf_read by focusing on creating a signable payload. However, the language is somewhat abstract and could be more concrete about the resource being acted upon.

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 context about when to use this tool (as the first step in creating a shelf) and explains the meaning of different rings. However, it does not explicitly state when not to use it or mention alternative tools like curate_signable or moderation_signable. The guidance is implied rather than 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 the description bears full burden. It clearly states 'NEVER moves money', a key behavioral trait. However, it lacks detail on side effects (e.g., does 'plans' write data?), error behavior, or idempotency.

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, well-structured sentence with no wasted words. Key information (resource, verb, constraints) is 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?

Tool has 2 params, no output schema, no annotations. Description explains high-level output (net, savings rate, by category) but not the precise format or expected structure of the expenses array. Lacks details on what 'plans' entails.

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 explains that income and expenses are inputs and outputs net, savings rate, by category, adding meaning. But the structure of the expenses array (e.g., required fields, item format) is not described, leaving 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?

Description clearly defines it as a household budget tool that shows and plans, with explicit statement 'NEVER moves money', distinguishing it from sibling tools like steward_cost_destroyed that probably move money. The verb 'shows', 'plans' and resource 'budget' are specific.

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 when to use (budget queries) and explicitly excludes money movement, but does not name alternative tools for moving money (e.g., steward_cost_destroyed). The context among siblings implies the distinction.

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 hints at a state change ('was -> now') but does not clarify if the tool is destructive or read-only, nor any 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?

Very concise (one sentence) but lacks structure: no action verb, no clear explanation of what the tool does.

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?

Incomplete for a tool with one parameter and no output schema. Does not explain what items are, what the tool returns, or side effects.

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%. The description does not mention the single parameter 'items' (array), providing 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 is vague: 'money you did NOT spend (was -> now), kept in your currency.' It does not state a clear verb and resource, nor does it distinguish from sibling tools like steward_budget.

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 or when not to use this tool. No alternatives mentioned.

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 full burden. It discloses key behavioral traits: each entry mints exactly one card, cards are non-duplicable and key-referenced. This reveals constraints and lifecycle, though it omits side effects like authentication or 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?

Single sentence with parenthetical clarification. No wasted words, front-loaded with key behavior and 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?

Given no output schema and 2 parameters (one required), the description covers core behavior but misses details like return value, how to 'extend' a study, and format of the cards array. Adequate for simple use but leaves gaps for precise 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 coverage is 0% and the description adds minimal detail. 'key' is required but its purpose (e.g., study identifier) is not explained. 'cards' is an array but the description says 'each entry mints ONE card', leaving ambiguity about the parameter's role (maybe entries vs cards). No 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 creates or extends a shared study, with specific behavior: 'each entry mints ONE card that lives once and is referenced by key; no duplication.' It distinguishes from siblings like study_export/import and cards_browse by emphasizing key-based reference and no duplication.

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 the tool is for creating/ extending studies but does not explicitly state when to use it versus alternatives like cards_browse or study_export. No exclusions or prerequisites are mentioned.

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 discloses that no private key is taken, which is a security trait. But it omits other behaviors like whether the export modifies the study or requires specific permissions.

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, no redundant words. The first sentence states the purpose, the second adds key behavioral and security details. Efficient and well-structured.

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 explanation of the 'key' parameter and what the bundle contains. While return value is mentioned, no output schema exists, and additional details about the format or usage of the result would be helpful.

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 only parameter 'key' has no description in the schema (0% coverage) and is not explained in the description. The description adds no 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 it exports a study as a portable bundle and returns the bundle with its hash. It specifies a security-related behavior (no private key). However, it doesn't explicitly differentiate from sibling tools like study_import, though the action is distinct.

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. It mentions how to handle the returned hash for identity binding but lacks context about prerequisites or use cases.

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?

Without annotations, the description must reveal behavioral traits. It mentions 'each lives once' hinting at uniqueness, but lacks details on side effects (e.g., does it overwrite existing cards?), authentication needs, or error conditions.

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 one sentence and front-loaded, but it lacks critical details. It could be more informative without being longer.

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 3 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain the bundle format, the role of key, or the effect of verify_signature.

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 mentions 'bundle' but doesn't explain the 'key' or 'verify_signature' parameters. No information on the nested bundle object structure.

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 imports an exported study bundle and re-materializes its cards. The verb 'import' and resource 'study bundle' are specific, and it differentiates from sibling tools like study_export and study_create.

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 study_create. It does not specify prerequisites or that it should be used after study_export.

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 fully carries transparency. It states the tool is deterministic, eliminates non-answers, and details each verdict meaning, especially cautioning against relaying SYSTEM_ERROR as a refutation. This is thorough and trustworthy.

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

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

The description is front-loaded with the core action and output, but the depth of detail makes it somewhat lengthy. While every sentence adds value, a slightly more structured layout could improve readability.

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 no output schema, the description covers return values (verdict, trail, receipt) and explains each verdict's meaning. It addresses both input forms and hints at domain coverage, making the tool self-contained for an 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?

The description adds significant meaning beyond the schema's 100% coverage. It explains the MATH form modes and the DOMAIN form step structure with an example (physics domain). It also clarifies the seal parameter default, making parameter usage concrete.

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 'claim', with specific outputs (verdict, trail, receipt). It distinguishes two major forms (MATH and ANY DOMAIN) and provides examples, making the purpose 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?

The description explains when to use both forms and mentions find_verifier for domain selection. It warns about SYSTEM_ERROR interpretation. However, it lacks explicit guidance on when not to use this tool (e.g., preferring badges_verify for badge claims), although context implies general applicability.

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 carries the full burden. It discloses that storage is never trusted (signatures are re-verified on read) and that invalid entries are reported rather than hidden. This adds useful behavioral context, but it omits side effects, auth requirements, rate limits, and any potential destructive 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?

The description is a single sentence, which is concise. However, it packs multiple ideas (witnesses, re-verification, trust, error reporting) without clear structure or front-loading of the primary action. A more structured approach would improve clarity while maintaining 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 tool has one parameter (content_hash) and no output schema, the description should explain what the response looks like (e.g., list of witnesses, verification status). It only mentions reporting invalid entries but does not describe the output format or structure, leaving the agent uncertain about the return value.

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 has 0% description coverage, and the tool description does not mention the 'content_hash' parameter at all. The agent must infer that 'a record' corresponds to this parameter. No format, constraints, or examples are provided, making it unclear what value to supply.

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 identifies the tool's purpose: to list who has witnessed a record. It adds behavioral details (re-verification, reporting invalid entries) that distinguish it from siblings like 'verify' or 'attest_record'. However, it does not explicitly use a verb like 'list' or 'get', leaving the action slightly implicit.

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. Sibling tools such as 'attest_record', 'verify', and 'audit' exist, but no comparative context is given. There is no mention of prerequisites, exclusions, or best practices for invoking this tool.

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