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

The description adds useful behavioral detail beyond the annotations: aliases are normalized and deduplicated, and an invalid `kind` value is refused before the alias is built rather than silently dropped. This meaningfully supplements the sparse annotation set without contradicting it.

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 main purpose is front-loaded in one clear sentence, and the `kind` explanation is cleanly separated. The enum list partially duplicates the schema, but it earns its place by adding the default and rejection behavior.

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 the key behavioral promise and the trickiest parameter (`kind`), and an output schema exists for return-value expectations. However, the meanings of `lang` and `script` are not addressed, and usage guidance relative to sibling tools is absent, leaving clear 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?

Only `kind` is explained: its allowed values, default of `other`, and validation behavior. The other four parameters — `person_id`, `value`, `lang`, and `script` — receive no semantics beyond their schema titles. With 0% schema description coverage, the description needed to compensate substantially more.

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

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

States a specific action and resource: 'Add a normalized-deduplicated alias to an existing person.' This is clear and the normalization/deduplication detail gives it specificity beyond a generic record tool. It does not explicitly contrast with sibling tools, so it stops short of a 5.

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 given about when to use add_alias versus alternatives such as record_fact, set_affiliation, or merge_people. The only implied signal is the tool's name and purpose, which is not enough to route an agent correctly among many overlapping 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?

Annotations only note this is not read-only, idempotent, or destructive; the description adds substantial behavior: never guess dates, temporal_basis inference rules, defaults for role and sensitivity, and that concurrent and historical memberships are kept. This goes well beyond the annotations, though it does not mention confidence handling or ID validation 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 purpose is front-loaded, and every sentence adds operational value—date-unknown handling, temporal_basis semantics, defaults, and retention behavior. The description is dense but not padded, and the detail is warranted given the complex date semantics.

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 write operation with tricky temporal semantics, the description is largely complete: it covers what to record, how to handle missing dates, how temporal_basis works, and defaults. The main gaps are the absence of confidence-field guidance and any explicit statement about what happens when IDs do not correspond to existing people or groups, though 'existing' is asserted in the purpose.

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 schema description coverage at 0%, the description compensates meaningfully: it defines temporal_basis values and inference, explains valid_from/valid_to handling, and states role and sensitivity defaults. It does not explain confidence or explicitly walk through every property, but the most semantically complex parameters are well covered.

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 opening sentence, 'Record that an existing person held a role in an existing group,' states the exact verb and resource. It clearly distinguishes this membership-recording action from sibling tools like create_group, close_group_membership, or set_relationship.

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 for when to use the tool: recording stated/confirmed memberships with role and date semantics. It does not explicitly name alternative tools or state exclusions, but the purpose and constraints are unambiguous enough to route an agent correctly.

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

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

Annotations only say the operation is not read-only, not idempotent, and not destructive. The description adds that the patch is a partial replacement ('leaves the rest alone') and that nothing is committed, which is critical side-effect information beyond the annotations.

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

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

Three short sentences with the purpose front-loaded in the first sentence. The second and third sentences add essential behavioral nuance without filler.

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 captures the key invocation decisions: staged vs committed, partial update, no commit side effect, and revised batch return (output schema covers return shape). The optional expected_batch_digest remains undefined, but the core workflow is well specified.

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 explains patch semantics (replaces named fields, leaves the rest alone), which is valuable because the schema has no descriptions and patch is an open object. batch_id and candidate_id are self-evident, but expected_batch_digest is not explained, leaving a gap given 0% schema description 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 opening sentence names a specific action ('Correct one staged candidate'), the target resource (a candidate within a staged batch), and the timing ('before it is committed'). It also states the return value ('returning the revised batch'), which distinguishes it from commit/withdraw siblings.

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 makes the pre-commit context explicit and adds that confirming an amendment is not acceptance of the batch, preventing use on committed records. It does not name sibling alternatives explicitly, but the staged/committed contrast gives clear context for when this tool applies.

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

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

Beyond the annotations (readOnlyHint false, idempotentHint false, destructiveHint false), the description adds concrete behavioral details: it refuses memberships that already have an end (`already_ended`) or an end before start (`ends_before_start`), and preserves earlier facts. These are not present in annotations, adding valuable context. However, it does not describe the success response or any side effects beyond the record update, but this is minor given the mutation context.

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

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

The description is concise (three sentences) and front-loaded with the core purpose, then usage, then constraints. Every sentence adds distinct value, and the structure is clear and scannable.

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 two-parameter schema and the existence of an output schema (not provided), the description covers purpose, usage, and constraints well. It lacks explicit mention of how to obtain a membership ID or the expected date format, but for a straightforward closure operation 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?

The schema has no descriptions (0% coverage) and the tool description does not explicitly explain the format or meaning of `ended_on` (e.g., date format) or how to obtain `membership_id`. It only implicitly suggests that `ended_on` is the last day the membership held, which is insufficient for an agent to correctly construct the 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 states a clear verb ('Record the last day') and resource ('a historically true membership'), and distinguishes this from the sibling tool `correct_record` by noting it is for valid memberships that ended, not for correcting wrong records. This provides a precise, unambiguous purpose.

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

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

It explicitly says 'Use this when someone left a group' and directs users to `correct_record` with entity type `group_membership` when a stored membership was simply wrong. This gives clear when-to-use and when-not-to-use guidance, directly addressing the main alternative.

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 opens with 'idempotently' while annotations set idempotentHint:false, a direct contradiction. It does disclose useful behaviors like whole-commit refusal and stale-batch rejection, but the contradiction with annotations is disqualifying.

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 short sentences with the core operation front-loaded and the two edge cases that matter following immediately. No filler or redundant restatement of the schema.

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 output schema and annotations, the description covers the important failure modes: withdrawn candidates and stale batch digests. The main missing pieces are precise definitions of batch_id and accepted_ids, plus resolution of the idempotency contradiction.

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 carry parameter meaning. It explains expected_batch_digest well, but batch_id and accepted_ids are only inferable from the tool name and the phrase 'accepted people and resolvable interactions.'

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

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

States a specific action ('Commit') and target ('accepted people and resolvable interactions'), adding the idempotency qualifier. This is more than a restatement of the tool name, though it does not explicitly contrast with siblings like review_import or import_content.

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 a post-review workflow ('from the review the user approved') and a safety rule around withdrawn candidates, so an agent gets some context. It never says when to choose commit_import over stage_candidates/review_import or when not to use it, so 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?

Annotations already indicate this is not read-only and not idempotent, and the description adds the specific active-to-completed state transition as well as the 'active' precondition. It does not address error behavior for already-completed or nonexistent reminders, but the annotations lower the burden and there is no contradiction.

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

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

A single sentence with no filler words; it is front-loaded with the verb and the object. The description is efficiently sized for the tool's simple purpose, though it omits some operational detail.

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?

Complexity is low and there is an output schema plus annotations, so the description does not need to explain return values. Still, it leaves open questions about how to obtain a valid reminder_id, whether inactive reminders are rejected, and what happens if the reminder is already completed — enough of a gap for a mutating 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 compensate by explaining reminder_id. It does not: no format, source, validation, or relationship to list_reminders/set_reminder is provided. The schema's title 'Reminder Id' is minimal and not augmented by the description.

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

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

The description states a specific verb ('Transition') with a clear resource ('one active reminder') and target state ('completed'), so the purpose is unambiguous. It could improve by explicitly distinguishing itself from sibling tools such as set_reminder or list_reminders, but it does not merely restate the name.

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 intended use is implied: call it when an active reminder should be marked completed. However, there is no explicit when-to-use vs when-not-to-use guidance, no mention of alternatives, and no note about needing a reminder ID from list_reminders or set_reminder.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description is not carrying the full safety burden. It adds useful behavioral context by stating that correction happens in place and that an audit trail with before/after values is produced. However, it does not disclose what happens when a field is not whitelisted or whether changes are reversible.

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

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

The description is one concise sentence with no filler. It front-loads the core action and includes an important behavioral detail (audit) without redundancy. It could be slightly more structured, but every word 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?

This is a mutating tool with three required parameters, a nested object, and no schema-level descriptions. The description omits critical operational details: what determines whitelisting, what entity_type values are valid, how multiple fields are handled, and what the output schema contains. An agent would likely need to infer too much before invoking the tool safely.

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 no descriptions and coverage is 0%, so the description must compensate for parameter meaning. It gives some context by saying 'whitelisted assertion fields,' which suggests what 'fields' contains, but entity_type and entity_id are only understandable from their names. No constraints, formats, or examples are provided, and 'additionalProperties: true' is left ambiguous.

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

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

The description uses a specific verb ('Correct') and a specific resource ('whitelisted assertion fields'), and it distinguishes the operation with 'in place' and 'before/after audit.' It is clear enough that it is not a generic record creation or search tool, though the term 'whitelisted assertion fields' is domain-specific and not elaborated.

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 no explicit guidance about when to use this tool versus sibling tools like record_fact, supersede_fact, or record_trait. The phrase 'in place' implies correcting existing records rather than creating new ones, but no alternatives or exclusion criteria 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?

Annotations only indicate readOnly=false, idempotent=false, destructive=false. The description adds critical behavioral detail beyond this: every call creates a new group even with an identical name, which explains the non-idempotency; it also discloses that sensitive/restricted groups are hidden from ordinary reads along with their memberships, and that organization_id does not create an affiliation. No contradiction with annotations.

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

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

The description is organized into three focused paragraphs: a one-line purpose, a non-idempotency warning and usage pointer, then parameter caveats. Every sentence carries meaningful information; no filler. Slightly verbose in the sensitivity explanation, but the structure front-loads the purpose and keeps important usage guidance near the top.

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 an output schema present, return values need no explanation. The description covers core semantics, non-idempotency, use-before-create guidance, parameter specifics, and visibility behavior. It does not mention error conditions, required permissions, or what happens if the organization_id does not exist, but these are not essential for basic invocation and the annotations plus schema cover the rest.

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 explains `organization_id` (must name an existing organization, only places the group under it) and `sensitivity` (defaults to `personal`, with visibility implications). `name` and `kind` are not explicitly described, but their meaning is clear from the opening sentence and enumerated kinds. The description partially fills the gap but leaves those two parameters to inference.

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

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

The description opens with a specific verb and resource: 'Create one identified group' and enumerates the kinds of groups (class, cohort, team, department, club, household, community). It differentiates itself from siblings by clarifying that 'an equal name is never treated as the same group' and directing users to `find_groups` when reuse of an existing group is intended. An agent can clearly distinguish this from lookup or membership 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?

The description gives explicit usage guidance: 'Use `find_groups` first and reuse the returned `id` when the user confirms it is the same one.' It also clarifies the behavior of `organization_id` (only places the group under an organization, creates no affiliation) and that a `sensitive` or `restricted` group is withheld from ordinary reads. This tells the agent when to create vs. reuse and what side effects to expect.

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

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

Beyond the readOnlyHint annotation, the description discloses label classification rules, temporal semantics (`overlap`, `disjoint`, `unknown`), the distinction between derived results and `direct_relationships`, the meaning of empty results, and truncation flags. This is rich behavioral 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 long but well organized into purpose, usage, output semantics, and caveats. Nearly every sentence carries necessary information, though it is dense and could be slightly tightened without losing 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?

For a complex analytical tool, the description covers key nuance: no result means no shared group found rather than no relationship, truncation flags signal partial answers, and labels/temporal states are precisely defined. The presence of an output schema removes the need to describe return fields, making this 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?

With zero schema description coverage, the description explains four of the five parameters by clarifying that people can be passed as IDs (`person_a_id`, `person_b_id`) or names (`person_a`, `person_b`). However, `limit` is not described in prose; its meaning is only implied by its name and default value, so parameter coverage is not complete.

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

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

The description states a precise action and resource: explaining how two people are connected through shared group memberships, including timing. It is specific enough that an agent can distinguish it from a generic connection search even without reading sibling schemas.

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 gives explicit target use cases: 'shared-background, introduction, and how do they know each other questions.' This is clear when-to-use context. However, it does not name alternatives such as the sibling `find_connection` or state when not to use this tool, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, covering safety. The description adds useful behavioral context by stating it returns exactly one path and a structured not-connected result. However, it does not disclose behavior around max_depth, multiple equally short paths, or how connection is determined.

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 focused sentence that front-loads the core behavior. Every word contributes meaning, and it avoids redundancy with the input schema.

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

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

The tool is relatively simple, has a readOnly annotation, and has an output schema that likely documents the return shape. Still, the complete absence of parameter semantics and usage guidance leaves gaps for an agent deciding how to invoke it, especially around max_depth.

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 for parameter meaning. It does not explain that person_a and person_b identify the people to connect, nor does it clarify how max_depth controls the search. The agent is left relying only on parameter names and titles.

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

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

The description states a specific verb and resource: return one shortest relationship path. The 'or a structured not-connected result' clarifies the fallback behavior. It does not explicitly differentiate from sibling get_relationship_graph, though 'one shortest path' provides some distinction.

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 no guidance on when to use this tool versus alternatives like get_relationship_graph or search_people. There is no mention of when a single shortest path is preferable, nor any exclusions or alternative tool references.

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

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

Annotations include readOnlyHint=true, so the bar is lower. The description adds meaningful behavioral context beyond that: results are candidates, not identity; sensitive/restricted groups are excluded; results are ordered by normalized name then id; and `truncated` reports more. This goes beyond the annotation without contradicting it.

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, front-loaded with the primary purpose, then adding essential caveats. Each sentence provides distinct value: the core function, the candidate/ambiguity warning, and the sensitive-group exclusion plus ordering/pagination. 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 moderate complexity (search with filters), an output schema exists, and annotations cover read-only behavior, the description covers key operational aspects: candidate semantics, sensitive-group exclusion, ordering, and pagination. The only gap is the lack of explicit mention of the `limit` parameter, but the `truncated` hint covers pagination behavior. Overall it is nearly complete for an agent to call this 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%, so the description must compensate. It explains `name` (normalized name contains) and `kind` (optionally of one kind) but does not explicitly explain the `limit` parameter. The mention of `truncated` reports more hints at pagination but does not describe the limit's role. Thus it partially compensates for the 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 states a specific verb (List) and resource (groups) with clear filter criteria (normalized name contains `name`, optionally of one `kind`). It clearly conveys what the tool does, though it does not explicitly name sibling tools to differentiate from, so it stops short of a 5.

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

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

The description provides clear context: results are candidates, not identity, and advises asking the user when multiple match. It also notes that sensitive and restricted groups are never returned, implying when not to use this tool for those. However, it does not explicitly name alternative tools or give 'when-not' conditions beyond these implicit exclusions, so it is a 4 rather than a 5.

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 annotations already declare destructiveHint=true and readOnlyHint=false, and the description aligns with that while adding useful context: the operation is a 'Hard-delete' and it redacts identifying audit history. It goes beyond the annotations by specifying exactly what kind of destructive action occurs and that audit data is also affected.

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, tight sentence with no filler. The primary action is front-loaded, and every word contributes meaning about the operation and its audit implication.

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 output schema and annotations reduce the need for return-value and safety details, but the two required parameters remain essentially unexplained. For a destructive tool like this, leaving 'target' and 'scope' open to interpretation is a significant completeness gap that the description does not fill.

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 neither 'target' nor 'scope' has description details. The description only hints that a person or record is involved, but it never explains what 'scope' means, what string values are expected, or whether scope selects the kind of entity, the deletion breadth, or the audit scope.

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

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

The description opens with the specific verb 'Hard-delete' and names the resource ('a person or record'), then adds the distinctive effect of redacting identifying audit history. This clearly distinguishes it from sibling tools such as correct_record, supersede_fact, and merge_people, which imply modification rather than permanent deletion.

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 what the tool does but gives no explicit guidance on when to choose it over alternatives. It does not mention that hard deletion should be reserved for cases where correction, supersession, or merging is insufficient, 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?

The description adds a meaningful behavioral detail beyond the readOnlyHint annotation: an ambiguous name returns candidates rather than guidance. This discloses fallback behavior that an agent could not infer from the schema or annotations. It does not discuss other behaviors like rate limits or authentication, but for a read-only retrieval tool the annotation and this fallback disclosure are reasonably sufficient.

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 compact and front-loaded: the first sentence states the core purpose, and the second sentence delivers the key parameter and fallback behavior. Both sentences earn their place with no redundant or promotional language.

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?

An output schema exists, so the return shape does not need to be described. However, all three parameters are optional, and the description does not explain what happens if neither person nor person_id is supplied, nor does it clarify the meaning or optionality of situation. These are meaningful gaps given the low schema coverage and the fact that this appears to be a person-dependent guidance 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?

With 0% schema description coverage, the description must compensate, and it does clarify person_id and person: person_id should come from resolve_person, while person can be a name or alias resolved inline, with ambiguity returning candidates. However, the situation parameter is left completely unexplained in both the schema and the description, which is a notable gap for a communication-advice tool.

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

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

The description clearly identifies the tool's action ('Return') and its resource ('sensitivity-gated signal for client-composed communication advice'), so an agent can understand the basic purpose. It does not explicitly contrast itself with siblings like get_person_context or set_communication_philosophy, but the resource is distinctive enough to avoid obvious confusion.

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 concrete usage context: pass person_id from resolve_person, or pass person as a name or alias for inline resolution, and notes that ambiguous names return candidates instead of guidance. This is clear operational guidance, though it does not explicitly state when to prefer this tool over alternatives 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?

Beyond the readOnlyHint annotation, the description discloses that sensitive/restricted records are never returned, affiliations have no disclosure level, unknown persons return found:false rather than error, signals are computed only over normalized values and inclusive validity periods, and valid_to null means 'no end set' rather than 'confirmed current.' This is substantial behavioral context beyond what annotations provide.

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 long but every section earns its place: purpose, resolution, signal semantics, affiliation semantics, read-only reassurance, sensitivity caveats, and error behavior. It is front-loaded with the core purpose and organized into clear thematic blocks with no filler.

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 output schema exists and annotations cover read-only behavior, the description adds the missing operational context: what signals mean, how affiliations should be interpreted, truncation caveats, sensitivity restrictions, and not-found behavior. An agent has enough to decide when and how to call this 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?

With schema description coverage at 0%, the description compensates well by explaining person_id ('from resolve_person') and person ('a name or alias to resolve inline'). However, the third parameter, limit, is not explicitly addressed; only indirect references to pagination and truncation appear.

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 opening sentence names a specific verb and resource: 'Return one person's stored facts, traits, observations, and affiliations and how they relate.' This clearly distinguishes it from sibling tools like get_person_timeline or search_people by focusing on consolidation evidence for maintenance.

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?

Explicitly says 'Use this before proposing maintenance' and explains that the tool 'decides nothing' while the agent must propose correct_record, supersede_fact, or merge_people. It also gives resolution guidance via person_id or person. It lacks an explicit when-not-to-use clause or named alternatives, so it stops short of a 5.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing important edge-case behavior: sensitive/restricted groups surface as found:false, and sensitive/restricted memberships are silently omitted without skewing truncated. It also clarifies the epistemic limitation that shared memberships are not proof members actually know each other.

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 tight sentences, with the primary action front-loaded and every additional sentence earning its place by adding behavioral caveats. There is no filler or redundant restating of annotations.

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

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

For a two-parameter read-only tool with an output schema, the description covers the non-obvious behavioral quirks that affect interpretation, which is the main completeness risk. Small gaps remain around explicit parameter semantics and sibling routing, but the schema and defaults cover most of what an agent needs to invoke it.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining group_id and limit, but it does not define either parameter. 'Bounded page' hints at limit-controlled pagination, but the description adds little explicit meaning beyond the schema's field names and default.

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 one group plus a bounded page of its recorded memberships, using a specific verb and resource. It does not explicitly contrast itself with siblings like find_groups or list_group_memberships, so it stops short of full sibling differentiation.

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

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

The description explains what the tool returns but gives no guidance on when to choose it over alternatives such as find_groups, list_group_memberships, or get_person_timeline. There are no explicit when-to-use or when-not-to-use conditions.

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

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

Beyond the readOnlyHint annotation, the description discloses meaningful behavior: minimal-disclosure output, narrow identity fields, active relationships and affiliations, a capped ranked facts/interactions slice, optional communication traits, sensitive-record suppression with no trace, and the truncated flag. This is rich behavioral context that helps an agent trust and interpret the result.

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 but efficient, with each sentence serving a distinct purpose: input routing, return contents, optional communication inclusion, and privacy/truncation semantics. It is front-loaded with the core purpose and uses code formatting to keep parameters readable.

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 output schema exists and the tool has five optional parameters, the description covers all necessary input semantics, output shaping, privacy behavior, and truncation signaling. An agent has enough information to call this tool correctly without further inference.

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 compensates by explaining every parameter: person_id, person, max_items, include_communication, and purpose (via the communication mention). It even documents special values and edge cases like ambiguous names returning candidates.

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

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

The description opens with a specific verb and resource: 'Assemble a minimal-disclosure context bundle for one person.' It clearly states what the tool returns and even ties person_id to resolve_person, but it does not explicitly differentiate itself from sibling tools like get_person_timeline or get_consolidation_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?

The description gives concrete input-routing guidance: pass person_id from resolve_person, or pass person to resolve inline, with ambiguous names returning candidates instead. This is clear operational context, though it does not explicitly state when to prefer this tool over sibling context tools.

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

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

Beyond the `readOnlyHint` annotation, the description discloses meaningful behavior: sensitive and restricted records are never returned, trait names only reference ordinary evidence, and unknown/removed persons yield `found: false` rather than an error. This gives the agent important expectations about filtering and failure modes.

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

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

The description is compact and front-loaded: the core behavior appears in the first sentence, followed by parameter guidance and behavioral caveats. Every sentence adds useful information without repetition or filler.

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 the essential invocation contract: how to identify the person, the ordering and boundedness, sensitive-record filtering, and not-found behavior. An output schema exists, so return structure does not need description. The only notable gap is the unmentioned `limit` parameter semantics, which is a minor completeness issue.

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 carry parameter meaning. It explains `person_id` versus `person` well, including the relationship to `resolve_person`. However, the `limit` parameter is not explained at all except via the implicit "bounded chronology" phrase, so one of three parameters remains underspecified.

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

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

The description opens with a specific verb and object: "Return one person's recent history, newest first, as a bounded chronology." This clearly identifies the resource (one person's history), the ordering (newest first), and the scope (bounded), which sufficiently distinguishes it from sibling tools like get_person_context or search_people.

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 explicit input guidance: pass `person_id` from `resolve_person`, or pass `person` by name/alias to resolve inline. It does not explicitly state when not to use this tool relative to siblings, but the clear one-person chronology framing provides strong contextual usage direction.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context by specifying 'active' relationships and 'capped for bounded disclosure.' This goes beyond the annotation without contradicting it.

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 compact and front-loaded with the primary purpose, followed by a concrete parameter instruction. No sentence is wasted.

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?

An output schema exists, so return-value documentation is not needed. However, with no schema-level parameter descriptions, the missing semantics for depth and types leave the definition incomplete for a tool with four optional parameters.

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 carries the burden of explaining parameters. It clarifies the relationship between person and person_id but leaves depth and types undefined, which is a significant gap for correctly invoking the tool.

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

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

The description states a specific action and resource: 'Return active relationship structure around one person,' which clearly identifies the tool's purpose. It does not explicitly differentiate from siblings like find_connection or get_person_context, so it misses full sibling distinction.

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 operational guidance on how to identify the person ('Pass person_id from resolve_person, or person ... to resolve inline'), but it does not state when to prefer this tool over related graph tools. Usage context is implied rather than explicitly scoped with alternatives 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds a useful behavioral nuance—only ordinary interactions count—but does not explain how staleness is determined, how threshold_days affects results, or whether people with no recorded interactions are included. No contradiction with annotations exists.

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 front-loads the action and object. Every clause earns its place: the qualifier 'ordinary interactions only' conveys scope without unnecessary elaboration.

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 readOnlyHint, output schema, and all-optional parameters, an agent can safely invoke the tool with defaults based on the description alone. However, the description does not clarify category semantics or how threshold_days maps to 'recently,' leaving some uncertainty for customized calls. It is adequate but not complete.

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

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

Schema description coverage is 0%, so the description should compensate for parameter meaning, but it does not mention limit, category, or threshold_days. 'Recently' loosely implies threshold_days, but category remains undefined. The tool description adds almost no value beyond the schema's property titles and defaults.

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

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

The description states a specific verb and resource: 'Return people you have not interacted with recently.' It also adds a meaningful qualifier, 'using ordinary interactions only,' which narrows the behavior. This distinguishes it from broad search or relationship-graph tools without being 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?

The description implies when to use the tool: when the goal is to find stale relationships. However, it gives no explicit when-not-to-use guidance or alternatives among the many sibling tools. 'Ordinary interactions only' hints at a boundary, but does not state when another tool should be selected instead.

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

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

Beyond the minimal annotations, the description discloses substantial behavioral details: path imports record a receipt so re-imports report the existing batch, forced stages a distinct processing session without weakening the duplicate rule, and only forced can bypass source_previously_redacted after a hard forget. It also explains the mbox-specific limitation and notes atomic staging, giving the agent a realistic model of 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 dense but every sentence contributes useful information: purpose first, then source types and self_sender, then the critical path/forced/dedup semantics. It is appropriately sized for the complexity of the tool and avoids filler or restating the schema.

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 source-type constraints, the dedup receipt behavior, forced re-imports, hard-forget edge cases, and mbox restrictions. It does not explicitly state whether path and content are mutually exclusive or clarify the content parameter directly, but the output schema and rich behavioral notes make the tool actionable 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?

With 0% schema description coverage, the description carries the full parameter burden. It explicitly lists valid source_type values, explains self_sender, and clarifies path and forced behavior. The content parameter is only indirectly referenced via 'inline content' in the mbox note, so it lacks a direct definition, preventing a perfect score.

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

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

The description opens with a specific verb phrase, 'Extract and atomically stage header-only candidates from a supported source without bodies,' clearly identifying both the action and the resource scope. It immediately distinguishes this tool from general body-import or full-content staging operations, and the source_type list makes the domain concrete.

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 contextual guidance: accepted source_type values are enumerated, self_sender is explained for chat exports, and the path/forced semantics detail when a repeat import is intentional. It does not explicitly name sibling alternatives like stage_candidates or commit_import, so it stops short of a full when-to-use-versus-X explanation, but the intended usage 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?

Beyond the readOnlyHint annotation, the description discloses bounded-page behavior, that only ordinary memberships in ordinary groups are returned, and that unknown/removed people yield found: false. This gives an agent useful expectations about output and edge cases.

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

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

Three concise sentences, each carrying distinct value: what the tool does, how to identify the person, and what filtering/edge-case behavior to expect. No filler or redundancy.

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

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

The description is complete enough for a read-only list tool with an existing output schema: it covers person resolution, filtering, and not-found semantics. The only minor gap is no explicit mention of pagination mechanics beyond 'bounded page', but the output schema likely covers that.

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 compensates for person and person_id by explaining their relationship to resolve_person and inline resolution. It does not explicitly explain the limit parameter, but 'bounded page' plus the schema default of 50 provides reasonable 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 states a specific verb ('Return'), a clear resource ('one person's recorded group memberships'), and a scope ('bounded page'). It is immediately distinguishable from sibling tools like find_groups, get_group, and add_group_membership.

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

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

Provides concrete invocation guidance: pass person_id from resolve_person, or pass person as a name/alias to resolve inline. It does not explicitly name alternative tools, but the context makes it clear this is for listing an individual's memberships rather than searching or mutating groups.

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 readOnlyHint annotation already signals a safe read operation. The description adds value beyond the annotation by disclosing the sort order and the inline person resolution behavior, giving the agent useful behavioral 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?

Two sentences with no wasted words. The main behavior and sort order are front-loaded, followed by concise filter instructions. Every sentence contributes 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 is acceptable for a simple read-only list tool, and the output schema reduces the need to explain return values. However, with 0% schema coverage and four parameters, the omission of status and due_before leaves meaningful gaps in the agent's ability to use those options 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%, so the description must compensate for all parameters. It covers person and person_id with filtering semantics, but completely omits status and due_before, leaving those parameters undocumented and the agent to guess their meaning and expected 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 verb 'List' and the resource 'pull-based reminders', and adds sorting behavior ('due-dated first and communication notes last') that distinguishes it from mutation siblings like set_reminder and complete_reminder. It also clarifies the scope of the listing, 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 provides clear filtering context: filter by person_id, or by person resolved inline, or omit both for all reminders. It does not explicitly mention when not to use this tool or name alternatives, but the read-only listing versus write tools is evident from the description.

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 annotations already mark this as destructive and not read-only. The description adds the important 'atomically' detail, but does not disclose consequences like whether the duplicate record is deleted, how conflicting fields are resolved, or whether the operation can be reversed.

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, compact sentence with no filler. Every word contributes meaning, and the core action and atomicity are stated 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?

For a destructive merge operation, the description is too thin. It does not explain merge behavior, field conflict resolution, whether the duplicate is removed, or any side effects on relationships and timeline data. An output schema exists, but that does not compensate for missing behavioral guidance on a destructive, irreversible action.

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 compensate, but it does not explain what primary_id and duplicate_id refer to or how they relate beyond their names. The names are somewhat self-explanatory, but the description adds no additional clarity about required ID types, ownership, or merge direction semantics.

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

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

The description uses a specific verb ('merge') and resource ('person'), clearly stating that a duplicate person is merged into a primary person. The word 'atomically' adds meaningful precision, though it does not explicitly distinguish this from the sibling tool resolve_person.

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 consolidating duplicate person records into a primary record. However, it gives no explicit when-to-use guidance or exclusions compared to alternatives like resolve_person or add_alias.

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

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

Annotations only indicate non-read-only, non-idempotent, non-destructive behavior. The description adds meaningful behavioral context by disclosing that `sensitivity` defaults to `personal` and that `sensitive` and `restricted` records are withheld from ordinary reads, which is not apparent from the annotations.

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

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

The description is two sentences with zero filler. The core action is front-loaded, followed by a high-value behavioral note and a sibling routing tip. 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?

Given the tool has 7 parameters and an output schema, the description provides a reasonable starting point but leaves gaps. It clarifies sensitivity behavior and one alternative tool, yet it does not clarify fact structure, time-range semantics, or how `predicate` and `value` should be formed, making it incomplete for a write tool with this many parameters.

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 carries the full burden for explaining parameters. It provides useful semantics for `sensitivity` and vaguely signals `valid_from`/`valid_to` through 'time-aware', but it does not explain `person_id`, `predicate`, `value`, or `confidence`, leaving major parameters underdocumented.

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 action ('Record'), the resource ('a time-aware fact'), and the target ('an existing person'). It also hints at differentiation from the sibling `remember` tool, though it does not distinguish itself from other record_* siblings like `record_observation` or `record_trait`.

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

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

The description explicitly advises using `remember` instead for a single statement named by a person's name, giving a clear routing signal. It does not, however, discuss when to prefer `record_fact` over other related tools such as `record_observation` or `record_trait`.

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

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

Annotations already declare the operation as non-read-only, non-idempotent, and non-destructive, so the description does not need to repeat those traits. The description adds the 'after validating all participants' precondition, but does not disclose what happens if validation fails, whether duplicates are possible, or what side effects recording may have.

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

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

The description is a single sentence with no filler or redundancy. 'After validating all participants' earns its place as a meaningful precondition, and the core 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 five parameters, no schema-level descriptions, and a large sibling set, the description is too sparse for reliable invocation. The presence of an output schema reduces the need to explain return values, but the optional parameters and the meaning of 'validating all participants' remain 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?

The schema has 5 parameters with 0% description coverage, so the description must compensate. It only weakly maps to 'summary' via 'interaction summary' and to 'participant_ids' via 'all participants', leaving channel, occurred_at, and sensitivity entirely 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 identifies a specific action ('Record') and a specific resource ('interaction summary'), which distinguishes it from sibling record_* tools such as record_fact or record_observation. The phrase 'after validating all participants' adds useful context, but it does not explicitly contrast this tool with similar siblings.

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 phrase 'after validating all participants' implies a sequencing requirement, which gives some usage context. However, there is no explicit guidance about when to choose this tool over record_fact, record_observation, or other sibling tools, nor any when-not-to-use instructions.

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

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

Annotations only flag the operation as non-read-only, non-idempotent, and non-destructive; the description adds that observations are 'separate from disclosed context,' which is useful behavioral context. It does not address duplicate behavior, correction flow, or permissions, but for a simple record operation this is acceptable.

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

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

One short sentence with no filler; the verb and key constraint are front-loaded. It is somewhat under-specified for the surrounding sibling set, but what is present is efficiently organized.

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

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

With 31 sibling tools and several record_* siblings, the description is too sparse to fully orient an agent. It omits any differentiation from record_fact, record_trait, or record_interaction and does not clarify what 'disclosed context' means. The output schema covers return values, so that omission is not the issue.

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 text, person_id, observed_at, or sensitivity. Parameter names are somewhat self-explanatory and required fields are visible in the schema, but the description adds no parameter-level meaning to compensate for the complete lack of 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 uses a specific verb ('Record') and resource ('subjective observation'), so it clearly states what the tool does. It does not explicitly differentiate from sibling record tools such as record_fact or record_trait, but 'subjective' and 'separate from disclosed context' narrow the meaning.

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 phrase 'separate from disclosed context' implies a when-to-use condition, but the description never names alternatives like record_fact or record_interaction. An agent gets only an implied trigger, not explicit guidance 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?

Annotations already indicate this is a non-read-only, non-idempotent, non-destructive write. The description adds mild behavioral context by saying the category is 'validated' and recommending that evidence be cited in evidence_note or evidence_ids. It does not contradict the annotations, but it also does not disclose broader behaviors such as overwrite semantics, duplicate handling, or failure modes.

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

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

The description is compact, front-loaded with the core purpose, and uses a short second paragraph for field-specific guidance. No sentence is wasted, and the structure makes the category constraint easy to scan.

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 seven parameters, zero schema description coverage, and many record-related sibling tools, this short description is not complete enough. It omits meaningful semantics for at least four parameters and provides no routing guidance among record_fact, record_observation, record_interaction, and remember. The output schema covers return values, but the input-side guidance remains insufficient.

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 carry most parameter meaning. It explains the category values and the role of evidence_note/evidence_ids, but it says nothing about person_id, value, confidence, or sensitivity. The required value parameter is especially underspecified, and confidence/sensitivity semantics are left entirely to the schema names and enum definitions.

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 and resource: 'Record a derived trait with validated category and provenance.' It goes beyond the bare name by specifying that the trait is derived and validated. It is reasonably distinct from siblings like record_fact and record_observation, though it does not explicitly name or contrast those alternatives.

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 phrase 'derived trait' and the enumerated categories imply this tool is for recording trait-level conclusions rather than raw observations or interactions. However, there is no explicit guidance about when to prefer this tool over record_fact, record_observation, or record_interaction, and no exclusions are stated. The usage context is present but only implied.

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 important behaviors beyond annotations: identity is never guessed, ambiguous/unconfirmed status returns candidates and records nothing, missing occurred_at causes refusal rather than defaulting to today, everything commits in one transaction and is audited. These are significant and non-obvious behavioral details that an agent needs to handle correctly.

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 but every sentence earns its place: purpose, usage trigger, identity resolution, field semantics, temporal behavior, failure mode, transaction guarantee, and alternative routing. The most critical constraints are front-loaded, and there is no filler.

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 complex 11-parameter write tool, the description covers all essential aspects: when to use, what each core parameter means, identity resolution behavior, failure/refusal conditions, and the recommended alternative tool. The presence of an output schema means return values need not be spelled out; the remaining gaps are minor auxiliary parameters already penalized in parameter semantics.

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 carry parameter meaning. It does so for the most important fields: person, org, role, relationship, note, kind, and occurred_at, with examples and the purpose of each. However, source, predicate, sensitivity, and trait_category are left unexplained, so compensation is strong but incomplete for all 11 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 opens with a specific verb and resource: 'Record one thing the user stated about one person, in a single call.' It clearly positions this tool as the direct-statement write path, distinguishing it from stage_candidates and the individual record tools by emphasizing the single-call consolidated behavior.

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?

Explicitly states when to use it ('when the user directly tells you something durable' with concrete examples) and gives a clear exclusion: material extracted or inferred from a transcript should go to stage_candidates. Also provides guidance for ambiguous identity: ask the user, then call again with the canonical name.

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 only generic false annotations, the description carries the behavioral burden. It discloses create-or-update semantics, durable persistence, alias merging into existing records, the is_self restriction, and the return info (person + created flag)—substantially beyond what annotations state.

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 compact sentences front-load the core action and use case, then pack alias semantics into the minimum necessary detail. No sentence is redundant or filler.

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 5-parameter upsert tool with an output schema, the description covers the essential call semantics, key parameters, merge behavior, and return values. The only omission, 'source', is a defaulted provenance field and does not block correct 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 explains name (matching key), aliases (object shape with kinds and merge behavior), summary (who they are), and is_self (only for the user), but leaves 'source' undocumented beyond its default.

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 first sentence names a specific verb and resource ('Create a new person or update the existing one matching `name`'), making the upsert behavior unmistakable. It also distinguishes this from relationship/fact tools like set_relationship and record_fact by focusing on the person record itself.

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

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

'Use this to durably record someone the user talks about' gives clear context for when to invoke it. It doesn't explicitly say when not to use it or name alternatives, but the context is specific enough to route an agent to this tool over fact/relationship 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?

The description substantially exceeds the readOnlyHint annotation by disclosing the ranking behavior, score/match reason output, ambiguity flag when candidates are close, and the meaning of an empty candidate list. This gives the agent a clear mental model of what will happen when the tool is invoked.

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 but well-organized: it opens with the core purpose, then gives usage order, expected output, ambiguity behavior, no-match fallback, and parameter strategy. Every sentence adds decision-relevant value and there is no filler.

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 read-only resolution tool with an output schema, the description covers the critical operational details: when to call it, how to interpret candidates, how to handle ambiguity, what an empty result means, and how to improve matching with hints. Nothing essential is missing for an agent to invoke it 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?

With schema description coverage at 0%, the description compensates well for query and hints: query is implied by 'name, nickname, or partial reference', and hints are explicitly described with org, role, and relationship plus guidance to prefer them over query. The limit parameter is not explained, though its name and default suggest it caps the number of returned candidates.

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

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

The description states a specific verb ('Resolve') and resource ('a name, nickname, or partial reference to candidate people'), and clearly distinguishes this tool from simple search by describing ranked candidates, match reasons, and ambiguity handling. This makes the tool's unique role immediately understandable.

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 explicit guidance: 'Call this first whenever the user mentions someone, before asking who they mean.' It also explains when to fall back to remember/remember_person on empty results and tells the agent to put context in hints rather than query. It does not explicitly name alternative tools like search_people, so the 'vs alternatives' guidance is only implicit.

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

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

Beyond readOnlyHint=true, the description discloses the optimistic-concurrency mechanism: the response carries a batch_digest and downstream mutations are refused on stale reads. This is valuable behavioral context that could not be inferred from annotations or the input schema.

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 short sentences with no filler: purpose first, then the critical digest hand-off behavior. Each sentence adds distinct information, and the most important workflow rule is stated directly.

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 readOnlyHint, a one-parameter input schema, and an output schema covering the response, the description is sufficient. An agent knows what it retrieves, that the result is tied to a batch, and what to do with the digest to avoid stale mutations. No critical calling information is missing.

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

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

With 0% schema description coverage, the description is the main carrier of parameter meaning. It clarifies that batch_id identifies a single batch ('for one batch') but does not state where the batch_id comes from or expected format. For a single self-explanatory required string, this is minimally adequate.

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 uses a specific verb ('Return') and names a concrete resource ('staged candidates and statuses') scoped to 'one batch.' The read-only framing clearly distinguishes it from batch-mutating siblings like amend_candidate, withdraw_candidates, and commit_import.

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 second sentence gives actionable workflow context: pass the returned batch_digest to amend_candidate, withdraw_candidates, or commit_import so the mutation is refused if the batch changed. It does not name alternative review tools or explicit when-not-to-use conditions, but the batch-scoped read workflow is clear.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context: results are 'ranked candidates' and the search is intentionally broader than exact identity matching. This goes beyond the annotation without contradicting it.

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 short sentences with no filler. The first sentence states the core action, the second provides routing guidance, and the third describes the output nature. Everything 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?

For a simple two-parameter read-only search with an output schema, the description covers purpose, scope, matching behavior, output style, and the key alternative. An agent has enough context to select and 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%, but the description compensates partially: 'free-text' clarifies `query` semantics and 'returns ranked candidates' suggests result ordering. However, `limit` is not explained in prose beyond its schema default, so the parameter guidance is incomplete.

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 leads with 'Free-text search over stored people for browsing or lookup,' giving a specific verb, resource, and use case. It also distinguishes itself from `resolve_person` by framing this tool as broader and candidate-returning rather than single-identity resolution.

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

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

It explicitly says to use this tool when you want to list known people matching a query, rather than to pin down a single identity, and names `resolve_person` as the alternative. This provides clear when-to-use and when-not-to-use guidance.

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

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

The description adds meaningful behavioral context beyond the readOnlyHint annotation: it requires a prior reindex, never downloads a model during query serving, and refuses to mix vectors from different model revisions. These are non-obvious operational traits that an agent must know to use the tool correctly.

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 dense, front-loaded sentences with no filler. The core purpose is stated first, followed by critical operational constraints. 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?

The description covers the essential operational constraints, prerequisites, and what the search targets, and an output schema exists so return-value details are not needed. It is slightly incomplete only because `kinds` and `limit` are left unexplained and no sibling comparison is offered.

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 carries the burden of explaining parameters. It clarifies that `query` is matched semantically and multilingually, but it does not explain the meaning of `kinds` or `limit`, nor how they constrain the search. This leaves the agent to guess at parameter semantics.

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

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

The description states a specific operation ('Search active people and safe interaction summaries') and the method ('multilingual semantic similarity'), which clearly distinguishes it from the lexical/relationship-focused sibling tools like search_people. The scope is concrete and an agent can infer what this tool is for without opening the schema.

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

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

The description implies when to use this tool: only after an explicit `pctx reindex --semantic` and only for semantic/local search. However, it does not explicitly contrast it with sibling alternatives such as search_people, nor does it state when not to use it. The prerequisite is helpful, but the selection guidance is incomplete.

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 annotations only provide negative hints (not read-only, not idempotent, not destructive), so the description carries the main burden. It discloses that the tool creates an affiliation and may resolve an org id or get/create an org by name, which adds useful behavioral context. However, it does not explain duplicate behavior, side effects on existing organizations, or whether existing affiliations are updated.

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 and front-loads the primary operation ('Create an affiliation'). It avoids filler, though the phrase 'get/creating by name' is grammatically awkward and could be smoother.

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 mutating tool with 6 parameters, no idempotency hint, and no usage conditions, the description omits important context such as how valid_from/valid_to/confidence should be used, whether duplicate affiliations are prevented, and whether the person must already be known. The output schema exists, but it does not make up for missing operational behavior.

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 for undocumented parameters. It only clarifies that 'org' can be an id or a name to resolve/create; the meanings of person_id, role, valid_from, valid_to, and confidence are left entirely to their names and JSON schema fields. This is insufficient for a 6-parameter tool.

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

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

The description uses a specific verb and resource: 'Create an affiliation', and clarifies that the org may be resolved by ID or get/created by name. It is reasonably distinguishable from sibling tools like set_relationship, though it does not explicitly name or differentiate itself from them.

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

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

There is no guidance on when to use this tool versus alternatives such as set_relationship or record_fact, and no mention of prerequisites like whether the person must already exist. The intended use is implied by the name and description, but the description leaves tool selection mostly to inference.

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 useful behavioral context beyond annotations: the philosophy is stored verbatim and only lengths are audited, implying no semantic content validation. However, it does not disclose important details such as whether the philosophy overwrites existing data, what the length limit is, or what happens when an audit fails. Nothing contradicts the annotations.

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

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

One short sentence with the action and resource front-loaded, containing no filler. The 'auditing lengths only' clause is compact and communicates an important behavioral constraint without wasting space.

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

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

For a simple single-parameter setter with an output schema, this is minimally adequate: the agent knows what to pass and that storage is verbatim. But the description omits practical details like overwrite behavior and the actual length audit threshold, so completeness is only partial.

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 carry the meaning of the single 'text' parameter. It does clarify that 'text' is the communication philosophy and that it is stored exactly, but it doesn't specify length constraints, formatting expectations, or limits, leaving a notable gap.

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

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

The description uses a specific verb ('Store') and a distinct resource ('communication philosophy'), and clarifies that the text is preserved verbatim. It clearly differs from read-style siblings like get_communication_guidance, though it does not explicitly differentiate it from other write/record 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?

There is no explicit guidance on when to use this tool versus alternatives like set_relationship or record_fact. The 'verbatim' phrasing implies exact storage rather than interpretation, but no exclusions, prerequisites, or sibling comparisons are given.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive operation, and the description's 'Create' aligns with that. The description adds useful context: relationship is directed and both people must already exist. However, it does not disclose behavior on duplicates, validation failures, or whether an existing relationship is updated or replaced.

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

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

A single, front-loaded sentence with no filler. Every word adds meaning, and the core semantics are immediately clear.

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 7 parameters, 0% schema description coverage, and no guidance on type or optional fields, the description is incomplete for reliable invocation beyond the minimal happy path. The output schema availability off-sets the need to describe return values, but the input parameter semantics are largely unexplained.

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 for parameter meaning. It only hints at subject_id and object_id via 'two existing people' and 'directed,' but it says nothing about the required 'type' parameter or optional label, confidence, valid_from, and valid_to. The agent is left to guess what types are acceptable and how temporal or confidence fields behave.

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

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

The description states a specific verb ('Create'), a clear resource ('relationship'), and key qualifiers: directed, between two existing people. This distinguishes the tool from read-only graph tools like get_relationship_graph and from other record-creation tools like record_fact or record_observation.

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

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

The description implies this tool is for person-to-person edges and that both endpoints must already exist, but it never explicitly says when to choose it over alternatives such as record_fact, record_observation, or set_affiliation. It provides no when-not-to-use or sibling-name guidance.

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

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

Annotations only signal a non-readonly, non-idempotent mutation. The description adds behavioral nuance by explaining that follow_up is dated, occasion recurs on a date, and communication_note is undated guidance surfaced with the person's context. This exceeds what the annotation booleans convey.

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 compact and front-loaded with the primary purpose, then uses a clean enum breakdown. Every sentence earns its place with no redundant filler.

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 core create semantics and kind behavior are well covered, and the output schema handles return-value expectations. However, the optional recurrence/due_at relationship is under-specified, especially how recurrence applies to occasion reminders, and there is no guidance on sourcing person_id beyond 'existing person.'

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 carries the burden for all 5 parameters. It richly explains the kind enum, and kind implications hint at due_at, but person_id, text, due_at, and especially recurrence are left to name-based inference. This is only partial compensation for the absent 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 opens with a specific verb and object: 'Create a reminder for an existing person.' It clearly distinguishes from sibling tools like list_reminders and complete_reminder by asserting creation semantics, and it scopes the operation to existing people.

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 for use: it creates reminders for existing people and defines when each reminder kind (follow_up, occasion, communication_note) is appropriate. It does not explicitly mention alternatives such as list_reminders or complete_reminder, so it lacks explicit when-not guidance.

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

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

Annotations only provide generic hints (not read-only, not idempotent, not destructive). The description goes far beyond that, disclosing hard limits (500 candidates, 128-char source, 1 MiB JSON, 8 KiB per string), duplicate-detection behavior via content_digest, the lack of name-based lookups, group merge semantics, and date/time inference rules. This is substantial behavioral context that an agent needs to avoid mistakes.

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 long but well-structured, with clear topic paragraphs for candidate types, attribution, groups, dates, and source fields. Every sentence adds necessary rules or constraints, and the most important purpose statement is front-loaded. It is not concise in absolute terms, but for a tool with this many nuanced rules, the length is appropriate, though it could potentially be tightened by moving some edge-case rules to a separate reference.

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, the description covers all critical domains: candidate types and their distinctions, attribution semantics, group references, date handling, source receipt fields, limits, and when to omit candidates. Because an output schema exists, return values are presumably specified there, so the description's focus on input semantics is appropriate. No essential information appears missing.

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

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

With 0% schema description coverage, the description must explain every parameter. It thoroughly covers `source`, `candidates`, `source_kind`, `content_digest`, and `extraction_fingerprint`, and touches `label` in the context of human wording. However, `external_source_id` is never mentioned, leaving one parameter undocumented. Still, the breadth and depth of the provided semantics are excellent, so only a small deduction is warranted.

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 first sentence states a specific verb and resource: 'Stage agent-extracted people, interactions, records, relationships, groups, and memberships.' This clearly distinguishes the tool from siblings like commit_import, review_import, or record_fact. Subsequent lines enumerate exact candidate types, leaving no ambiguity about the tool's 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 explicitly says 'Use this after extracting concise candidates from user-provided notes, meeting transcripts, or other agent-visible text.' It also gives exclusions, e.g., omit sensitive relationships rather than staging them, and names an alternative: 'resolve an existing group with `find_groups` first.' These are clear usage conditions and alternative routes.

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 goes well beyond the annotations, explaining that the old fact is closed the day before effective_from, the replacement inherits the old end date, confidence/sensitivity inherit when omitted, and both rows commit atomically. These behavioral details are critical and not available from annotations or schema.

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 then efficiently adds the key behavioral constraints and transaction guarantee. Every sentence carries meaning; there is no filler or repetition.

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 gives an agent everything needed to select and invoke this tool correctly: the scenario, the alternative, the exact closure/inheritance behavior, parameter semantics, and atomicity. An output schema exists, so not describing return values is acceptable.

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 compensates substantially by explaining effective_from semantics, the inheritance behavior of confidence and sensitivity, and the fact that person, predicate, and replacement end date cannot be changed. fact_id and new_value are not explicitly described, but their meaning is clear from the operation's purpose.

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

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

The description uses a specific verb phrase, 'Close a fact that was true and open its replacement from an effective date,' which precisely identifies the operation and resource. It clearly distinguishes supersede_fact from correct_record by stating that it applies when a value was historically correct, not simply wrong.

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 when-to-use guidance: use when a stored value was historically correct and the real-world state changed. It also names the alternative, correct_record, for the case where a value was simply wrong, and lists what cannot be changed in this operation.

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 readOnlyHint annotation already signals a read-only operation, and the description reinforces that with 'Return'. It adds useful behavioral details: the window is inclusive, reminders must be dated and active, and the result can be narrowed by person. No contradiction with annotations.

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

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

The description is short, front-loaded with the action, and every sentence contributes: the first defines the result set and window, the second explains optional filtering. There is no filler or redundancy.

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

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

With an output schema present and a readOnlyHint annotation, the description covers the core behavior adequately. However, it does not clarify window_days semantics or the interaction/precedence of person_id vs person, leaving a meaningful gap for an agent choosing parameters.

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 explains that person can be a name or alias and that person_id/person narrow results, but it does not explain window_days beyond the vague 'upcoming window' phrase. The default value of 30 and the parameter name provide partial meaning, but the description itself leaves a gap.

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

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

The description uses a specific verb ('Return') and names the resource ('ordinary birthdays and dated active reminders inside an inclusive upcoming window'), making the tool's purpose clear. It does not explicitly distinguish itself from sibling tools such as list_reminders, though the combined birthday/reminder scope partially separates it.

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 optional person filtering but gives no guidance on when to choose this tool over similar siblings like list_reminders or get_person_context. There are no exclusions, prerequisites, or alternative-selection cues.

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 annotations already indicate this is not read-only, not idempotent, and not destructive, but the description adds valuable specifics: withdrawn candidates remain listed as 'rejected' and are never committed, and nothing else changes. This goes beyond the annotations by clarifying the exact side effect on the batch, which is essential for an agent to understand the tool's impact.

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 fluff. The primary action is front-loaded, and the second sentence adds essential behavioral details without redundancy. Every word earns its place, making it highly efficient for an agent to parse.

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 an output schema exists (so return format is covered), the description leaves the optional expected_batch_digest parameter undocumented. The main behavior is well explained, but an agent may not know why the digest parameter exists or how to use it. Given the tool's relative simplicity and the presence of an output schema, the description is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must explain parameter meanings. It does not mention batch_id, candidate_ids, or expected_batch_digest at all. While batch_id and candidate_ids are somewhat self-explanatory from their names, the optional expected_batch_digest is completely unexplained, leaving a significant gap for an agent trying to decide whether to provide it or what it should contain.

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 'Drop' and the resource 'staged candidates', and mentions the result 'returning the revised batch'. It also adds a distinctive behavioral detail (candidates become 'rejected' and are never committed) that distinguishes it from sibling tools like stage_candidates or commit_import. This makes 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 implies usage for removing candidates before a commit, but it does not explicitly state when to use this tool versus alternatives such as amend_candidate or commit_import. It gives behavioral context that helps infer usage, but there is no explicit guidance on exclusions or alternative selection. This leaves some ambiguity for an agent.

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