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?

Annotation Contradiction: the description explicitly says the operation is 'idempotently' performed, while annotations set idempotentHint to false. The description also does not disclose side effects, failure behavior, or what happens to already-committed IDs, which matters for a mutation-like commit operation.

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 short sentence with no filler, and the primary verb and object are front-loaded. It is concise, though the brevity sacrifices needed behavioral and contextual 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?

Even with an output schema present, an agent cannot determine the intended workflow, what 'accepted' means, how accepted_ids relate to prior staging/review tools, or whether retries are actually safe. The idempotency contradiction further undermines completeness.

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

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

Schema description coverage is 0%, so the schema provides no parameter documentation. The description only loosely ties 'accepted people' to accepted_ids, and batch_id is completely unexplained. The description does not compensate for the absence of parameter meaning.

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

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

The description states a clear verb ('Commit') and resource ('accepted people and resolvable interactions'), so an agent can infer this finalizes imported candidates. It does not name a sibling tool for differentiation, but the action is specific enough to be useful.

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 this tool versus stage_candidates, review_import, or import_content. The phrase 'accepted people' implies it follows some review/acceptance step, but the description never states preconditions or alternatives.

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

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

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 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?

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 concrete behavior: no writes, sensitive/restricted records are never returned, ordinary evidence only, unknown/removed person yields found:false, and signals are computed from normalized values and inclusive validity periods only. It also states the tool 'decides nothing,' which is important behavioral context for an autonomous agent.

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 main purpose, then parameters, then use context, signal semantics, and safety guarantees. Despite length, each sentence carries distinct information necessary for safe and correct use, with no redundancy.

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

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

With an output schema present and rich annotations, the description covers the essential invocation context, signal taxonomy, maintenance workflow, privacy behavior, and error behavior (found:false). It leaves no operationally critical gap for an agent deciding whether and how to call this 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 carries the burden. It explains person_id and person ('Pass person_id from resolve_person, or person... to resolve inline') but does not explain limit or how the two identification parameters interact when both or neither are provided. The description adds real meaning for the core parameters but leaves one schema field undocumented.

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

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

The opening sentence names a specific verb ('Return') and resource ('one person's stored facts, traits, and observations plus how they relate'), making the tool's scope unambiguous. The maintenance-focused use and signal names separate it from siblings like get_person_context and get_person_timeline.

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 before proposing maintenance' and explains that reading evidence and proposing correct_record, supersede_fact, or merge_people is the agent's job. This gives a clear when-to-use instruction and routes downstream actions, even though it doesn't name a negative 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?

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?

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?

Annotations already declare readOnlyHint=true, and the description's 'Return' aligns with that. The description adds that it returns staged candidates and statuses per batch, which is useful scoping, but it does not disclose behavior such as error handling for unknown batch IDs, possible empty results, or whether statuses follow a particular workflow.

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

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

The description is a single front-loaded sentence with no wasted words. Every term contributes: 'Return' states the action, 'staged candidates and statuses' states the output, and 'one batch' states the scope. This is an appropriately sized definition for a simple single-parameter tool.

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 tool with one parameter and an output schema, the description covers the essential behavior: what it returns and for what scope. It is complete enough to call correctly with a valid batch_id. The main missing piece is linkage to the staging workflow, but the output schema and annotations cover return values and safety.

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

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

There is one required parameter, batch_id, and schema description coverage is 0%. The description only says 'one batch,' which adds minimal conceptual meaning but does not explain where batch_id comes from, what format it takes, or how it relates to stage_candidates. Given the low schema coverage, the description should compensate more but does not.

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 a clear resource ('staged candidates and statuses') scoped to 'one batch.' This clearly differentiates it from sibling staging and commit tools like stage_candidates and commit_import, which involve different stages of the import flow.

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 is the tool to inspect previously staged candidates for a specific batch, but it does not explicitly say when to use it versus stage_candidates or commit_import. It also does not state that a batch must already exist or have been staged before calling, which is useful context for correct usage.

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

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

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 say not read-only, not idempotent, not destructive, so the description carries the behavioral burden and does so thoroughly. It discloses candidate-count and string-size limits, relationship confidentiality rules, the ban on raw source text in candidate fields, SHA-256 based duplicate detection, and source_kind formatting constraints. No contradiction with annotations: the described write-and-detection behavior is consistent with readOnly false.

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 organized into semantic blocks: candidate types, constraints, confidentiality, evidence linking, and source receipt fields. It front-loads the core purpose before edge cases. A small amount of redundancy exists, such as the no-source-text rule stated more than once, but the density is justified by the tool's complexity.

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

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

For a complex 7-parameter tool with 0% schema descriptions and minimal annotations, the description supplies the operational essentials: candidate semantics, evidence-ref policy, disclosure behavior, size limits, and source handling. An output schema exists, so omitting return-value explanation is acceptable. An agent can select and invoke this tool correctly from the text alone.

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

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

Schema coverage is 0%, and the description compensates substantially: it defines `source` limits, `source_kind` syntax, `content_digest` format and duplicate-detection role, `label` as the human-readable field, and trait evidence fields. However, `external_source_id` is never mentioned and the nested candidate structure is only partially specified, so not every parameter receives full treatment.

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 the verb 'Stage' and enumerates the exact resource types: people, interactions, affiliations, facts, observations, traits, and relationships. It also frames the distinct batching/provenance role, which separates it from the individual record_fact/record_observation/record_trait 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 gives an explicit trigger: 'Use this after extracting concise candidates from user-provided notes, meeting transcripts, or other agent-visible text.' It does not explicitly name alternatives or state when not to use it, but the context is clear enough for routing.

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.