noticed

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds significant behavioral context: it clarifies the target/first record survives and the user's own person always survives, notes reversibility (admin can undo), and explains the needs-confirmation response with a token, including the instruction not to pre-set the token. These details go well beyond the annotations.

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

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

The description is long but information-dense, with the core purpose and identification options up front, followed by behavioral caveats. Every sentence contributes meaningful guidance, but the density makes it slightly harder to parse quickly. It is well-structured overall.

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 merge operation with a destructive hint, the description covers all essential aspects: identification methods, survival rules, reversibility, the confirmation flow with token, and the admin-only restriction for verified sign-ins. The output schema exists, so return values need not be explained. Nothing critical is missing.

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

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

The schema covers 100% of parameters, but the description adds valuable usage semantics: which combination of parameters to use (candidate_id vs person_a+b vs profile_a+b), that profile_a+b is for the email→person queue where candidate_id is null, and the confirmation_token usage. This enhances the schema descriptions rather than simply repeating them.

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

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

The description states the verb 'Accept' and the resource 'a PENDING identity match' with the outcome 'merge the two records into one'. It clearly differentiates from sibling tools like dismiss_identity_match (reject) and mark_different_people (mark as different) by specifying the merge action.

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 explains when to use it (for a pending match), how to identify the match (candidate_id, person_a+b, or profile_a+b with a note on which queue), and the confirmation flow when conflicting evidence exists. It also mentions admin-only for verified-sign-in conflicts. It does not explicitly name sibling alternatives like dismiss_identity_match, but the context is clear enough.

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 destructiveHint=true and idempotentHint=false, so mutability is covered. The description adds behavioral clarity by specifying the effect: 'A suggested add becomes a member; a suggested removal is removed.' This goes beyond annotations by clarifying the actual outcome of the operation, which is useful context for the 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 two sentences with no redundancy. It leads with the core purpose, then clarifies the two possible outcomes. Every word earns its place; it is concise and well-structured.

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

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

Given the tool's simplicity, the output schema (which defines return values), and the annotations covering safety, the description is complete. It covers the action, the scope ('one pending'), and the result. There is no missing information needed to call 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 100% for all three parameters (list_id, list_name, person_id) with explanations for each. The description does not add any parameter-specific guidance beyond what the schema already states. Since the schema fully documents the parameters, the baseline of 3 applies.

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

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

The description clearly states the action: 'Accept one pending add/remove suggestion for a list.' It specifies the resource (a pending suggestion on a list) and distinguishes the outcome for adds vs. removals. This differentiates it from sibling tools like reject_list_suggestion, add_to_list, and remove_from_list by focusing on accepting a suggestion rather than directly modifying membership or rejecting.

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

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

The description implies usage context: it is for accepting pending suggestions on a list. However, it does not explicitly name alternatives or provide when-not-to-use guidance. For instance, it does not mention that reject_list_suggestion should be used instead to decline, or that add_to_list/remove_from_list are for direct actions. The guidance is adequate but not explicit about 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 this a safe, idempotent, non-destructive, closed-world read, so the description's main added value is enumerating the status vocabulary (pairing, syncing, synced, partially synced, need attention) and the platform scope of the check. That is genuinely useful, but it says nothing about staleness of the status, what triggers a re-check, or any auth prerequisites for seeing session-based data.

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

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

Three sentences, front-loaded with the core purpose, then the status dimension, then the Teams payload. Dense but each sentence carries information; the only slack is the slightly rambling status list and the 'noticed' phrasing that adds nothing.

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 parameterless read tool with an output schema and full annotation coverage, the description is close to self-sufficient: it frames the scope, the domain of results, and one cross-tool usage of the returned data. The one meaningful omission is disambiguation against the near-duplicate sibling get_connected_source_status.

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

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

With zero parameters, the baseline is 4, and the description does a bit extra by explaining that the returned team_id is the value to supply elsewhere for scope:'team' reads, which ties this tool's output to other tools' parameters. No input semantics are needed here, so there is no gap to compensate for.

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 names a specific resource (connected accounts across the browser extension and iOS embedded-browser sessions) and enumerates what it reports: GitHub/LinkedIn connection state, LinkedIn/X import states, and a Teams listing. It is clear what the tool returns, but it never distinguishes itself from the very similarly named sibling get_connected_source_status, which an agent could easily confuse it with.

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

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

It gives explicit usage framing ('Use this to see whether GitHub and LinkedIn are connected...') and adds a downstream purpose note that the returned team_id is what to pass for scope:'team' reads. It stops short of any exclusion guidance, so the overlap with get_connected_source_status and sync_connected_source is left unresolved.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description's job is to add context and it does: it defines the epistemic bar for a valid memory and states that @mentioning links a person in the network. It doesn't warn that a non-idempotent write may create duplicate memories on retry, which would be the one remaining behavior worth disclosing.

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?

Four sentences, front-loaded with the defining constraint, then disambiguation, then the linking mechanic, then the read-back path — no filler. The ALL-CAPS emphasis is heavy-handed but each sentence carries a distinct routing or behavioral fact.

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 write tool with full schema coverage, an output schema, and supporting annotations, the description supplies the missing piece — the judgment call about what counts as this agent's memory versus a user note. Only the retry/duplication behavior of a non-idempotent write is left unstated.

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

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

Schema description coverage is 100%, so the schema already documents person_id, content, tags, occurred_at, and captured_via. The description only adds the @mention linking behavior for content, which is largely duplicated in the schema's own content description, and says nothing about occurred_at or captured_via. Baseline 3 is appropriate when the schema carries the parameter burden.

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 verb and resource ('Save a MEMORY') and immediately narrows scope to 'a SPECIFIC person' and to information the agent inferred rather than was told. The negative definition ('something YOU worked out on your own, unprompted, that the user never told you') distinguishes it from add_note and memory_save without requiring schema inspection.

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?

Gives explicit routing rules both ways: if the user asked you to remember it, use add_note; if the fact isn't about one person, use memory_save. It also names the read path (get_person, relationship.memories) so the agent knows this tool is write-only in the workflow.

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 this is a non-read-only, non-destructive, non-idempotent write. The description adds genuinely useful behavior beyond that: the note is attributed to the user, @mention syntax in content creates network links, and notes are retrievable through get_person. It does not warn about duplicate notes from repeated calls (consistent with idempotentHint=false) or mention any permission requirements, which keeps it short of a 5.

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?

Front-loaded with the core action, then triggers, then the exclusion, then linking and read-back — a sensible order. Slightly padded by rhetorical phrasing ("The note is theirs; you're just the keyboard"), though that line does convey the authorship constraint.

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

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

For a 5-parameter write tool with full schema coverage and an output schema, the description covers selection criteria, the sibling exclusion, the linking mechanism and the retrieval path. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so person_id, content, occurred_at, captured_via and tags are already documented in the schema. The description's only parameter-adjacent content, @mention linking in `content`, duplicates the schema text verbatim, and it says nothing about occurred_at or captured_via. Baseline 3 applies.

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

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

States a specific verb and resource ("Write a NOTE on a person's record") and immediately qualifies the content as user-supplied. It explicitly distinguishes itself from the closest sibling, add_memory, so an agent can route without opening either 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?

Gives concrete trigger conditions with quoted example utterances ("remember Rita prefers async", "note that Ana is hiring"), an explicit negative case (self-inferred facts go to add_memory), and the read-back path via get_person (relationship.notes). Both when-to-use and when-not-to-use are covered.

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 declare destructiveHint=true and idempotentHint=false without saying why; the description explains the destructive path, which is that if the URL already belongs to another record in the network, noticed merges the two records, and an admin can reverse that merge. It also documents the failure mode: a profile that conflicts with verified identity evidence is rejected with an error, and the description notes that noticed treats the URL as an assertion by the caller rather than as verified truth.

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 action and the input, then layers on side effects and exclusions, and every sentence carries information you cannot get from the schema or annotations. The parentheticals are dense but they orient the reader rather than padding the text.

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

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

For a two-parameter mutation tool with complete annotations and an output schema, the definition covers the remaining unknowns: what happens on success, the merge side effect, reversibility, and the rejection condition. Nothing an agent needs in order to decide whether to call it, or to call it correctly, is missing.

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

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

Schema coverage is 100%: both parameters are documented, including the accepted URL formats and where person_id comes from. The description adds only the semantic framing that the URL is treated as an assertion, not a proof of identity, but it adds no format or edge-case detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Give noticed a LinkedIn or GitHub URL for a contact missing a profile') and explicitly states the scope: attaching a profile to a thin contact, not merging two existing records. It names the sibling tools that do the other job (accept_identity_match / suggest_identity_match), so an agent can tell the two apart without opening a 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 says explicitly when to use the tool: for a contact that is missing a profile, typically an email-only person surfaced by list_profile_gaps, and it says which parameters to pass. It also gives the exclusion ('not to merge two existing records') and routes the agent to the correct alternatives, which is stronger guidance than most definitions provide.

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

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

The description discloses idempotency and the confirmation side-effect, which goes beyond the annotations (idempotentHint: true). It adds valuable behavioral details that are not obvious from the tool name or schema. However, it doesn't mention error cases or authorization requirements, but given the annotations already cover readOnlyHint and destructiveHint, this is 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 concise: two sentences that front-load the core action and the key side-effects (idempotent, confirmation) before parameter selection details. Every sentence adds value, and there is no fluff.

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

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

Given the availability of output schema and full parameter documentation, the description is well-rounded. It covers the core behavior, side-effects, and parameter selection logic. It could mention what happens if the list is not found, but that is a minor gap given the schema and the existence of list_lists for reference. The description is complete enough for an agent to call this tool correctly.

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

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

The schema coverage is 100%, describing each parameter and its source. The description adds the clarification that list_id and list_name are mutually exclusive alternatives ('Pass this OR list_name'). This adds meaning beyond the schema descriptions, which already are detailed. The description doesn't add anything about person_id beyond what the schema says, but the schema is sufficient, so a baseline of 3 is appropriate.

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

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

The description clearly states the action ('Put a person on a list') with a specific verb and resource, and distinguishes it from alternatives like remove_from_list and accept_list_suggestion. It also notes the idempotent behavior and the confirmation side-effect, which is a clear differentiator from similarly named 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?

Explicitly says to identify the list by list_id or list_name, and the person by person_id from specific source tools (search_people/resolve_person). While it doesn't explicitly say when not to use it, the clear mention of alternatives (e.g., accept_list_suggestion) and the confirmation behavior provides strong usage context. The description implies that if a person is merely suggested, this tool confirms them, which guides the agent on when to use this versus accept_list_suggestion.

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 establish the safety profile (not read-only, not destructive, idempotent), and the description adds substantial behavior on top: the dedupe short-circuit returns `{ created:false, potential_duplicates, confirmation_token }` instead of creating, and relationship_types supplied on a dedupe-flagged call are discarded and must be re-supplied. Those are non-obvious side effects an agent would otherwise stumble into.

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 definition is front-loaded and dense with zero filler sentences — the known-vs-new rule comes first, then the dedupe caveat, which is the right priority order. It loses a point for repetition: "set it right here at add time, no follow-up update_person needed" appears in both the description and the relationship_types schema text, and the DEDUPE block is written in compressed shorthand that takes a second read.

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

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

For a mutation tool with six optional parameters, a nested free_form object, and an output schema, the description covers the things an agent must know before calling: which identity path to take, what dedupe returns, and how to recover from it. Return-value shape is delegated correctly to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema cannot express: person_id and free_form are described as mutually exclusive alternatives ("Accepts person_id OR free_form"), which the schema's flat additionalProperties:false does not enforce or communicate. It also clarifies that relationship_types is set at add time and saved without a second call, though it largely restates the closed-set rule already documented in the schema.

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

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

"Add someone to your network" states a specific verb and resource, and the description immediately splits the operation into two concrete modes: known person (person_id → tracked) and new person (free_form → created/imported + tracked). That two-path framing tells an agent exactly what the tool does and how it differs from siblings like update_person 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?

It gives explicit routing rules: use person_id when you have a search_people hit, use free_form when there is no person_id, and set relationship_types at add time rather than follow-up with update_person. It also states the when-not path for creation — if you get potential_duplicates, track the existing person instead of re-calling, and only re-call with confirmation_token after user confirmation.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, but the description adds genuinely new behavioral context the annotations cannot convey: cancellation cascades to descendant runs while already committed findings are preserved. It still omits what happens to in-flight or partial (uncommitted) work, which is the main open question for a cancel 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?

A single sentence with zero waste, front-loading the action and immediately qualifying the scope and data-preservation behavior. Nothing redundant with the title or annotations.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile; the description supplies the cascade and preservation semantics that structured fields lack. It is largely complete for a one-parameter tool, with only the handling of uncommitted work left unspecified.

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?

One parameter (run_id, uuid) with 0% schema description coverage, so the description must carry the semantics; it does not explain run_id explicitly, though the name makes its meaning inferable. With only a single self-evident identifier, the gap is minor, landing at the minimum-viable level rather than the 0-parameter baseline.

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 verb (cancel) and resource (a research run, plus its descendants), which is clearly distinct from research_person, research_status, and submit_enrichment_research. It stops short of naming the sibling you would use to inspect a run before cancelling, so sibling differentiation is implied rather than explicit.

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 never says when to cancel versus checking status with research_status first, nor what preconditions apply (e.g. must the run be in-progress). An agent can infer the basic intent from the verb, but there are no exclusions or alternatives offered.

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 cover the behavioral profile: readOnly=false, idempotent=true, destructive=false, and openWorld=false. The description adds no behavior beyond that; it does not say whether completion records a timestamp, whether it can be undone, or what happens when the action is already done. Given the rich annotation set, a 3 is appropriate, but this description is not a strong example of added context.

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

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

Two short sentences with zero filler. The action purpose is front-loaded, and the identifier-discovery hint follows immediately.

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

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

For a single-parameter mutation with an output schema and a full annotation set, the description covers what is needed to select and call the tool. The only shortfall is that it does not explain the irreversibility or the post-condition of marking an action done.

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

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

Schema coverage is 100%, so baseline would be 3. The description nonetheless adds real value beyond the schema's bare "The action to complete" by naming the two concrete sources for action_id (get_person relationship.actions and list_actions). That provenance guidance is not in the schema.

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

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

The description states a specific verb and resource: "Mark a follow-up / action done". This clearly distinguishes the tool from create_action, delete_action, and update_action, which all operate on the same resource. It stops short of an explicit contrast with update_action, but the intent is 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 usage guidance is limited to telling the agent where to obtain the action_id, via get_person (relationship.actions) or list_actions. This is practical help with the prerequisite. However, it does not say when to use this tool instead of update_action, or whether the action can be marked done only once.

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, destructiveHint=false, and idempotentHint=true, but the description adds valuable behavioral context beyond that: the locking mechanism ('after the first answer locks the question'), the specific idempotency condition ('Identical normalized configuration is safe to retry'), and the rejection of changed locked configuration. It also clarifies side effects by stating it does not write answers or change members. This significantly enriches the agent's understanding of the tool's behavior.

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

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

The description is three sentences, front-loaded with purpose, then permission, idempotency, return values, and side effects. Every sentence carries essential information with no filler. The structure is logical and efficient.

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

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

Given the existence of an output schema (which covers return values) and the presence of annotations, the description covers key aspects: permission, idempotency, side effects, and the return of canonical_url and review_url. The main gap is the lack of parameter explanations, but for a configuration tool with moderately self-explanatory parameter names, it is fairly complete. A slight deduction for not elaborating on feedback_type or the exact meaning of 'context'.

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

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

Schema description coverage is 0%, so the description must compensate. However, it only vaguely mentions 'question/context' and does not explain parameters like list_id, list_name, description, or feedback_type. While some parameter names are self-explanatory, feedback_type and description could have ambiguous meanings. The description provides minimal semantic guidance for parameters beyond what the names imply, leaving the agent to guess.

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 ('Configure') with a clear resource ('a list's review question/context') and a temporal scope ('before human answers begin'). It also explicitly distinguishes itself from other actions by stating what it does not do ('Does not write answers or change members'), which helps differentiate it from siblings like add_to_list or update_list.

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

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

It states when to use it ('before human answers begin') and the permission requirement ('Requires edit access'). It also explains idempotency behavior, which guides retries. However, it does not explicitly name alternative tools or say when not to use it, though the purpose is clear enough that an agent can infer appropriate usage from context.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds value beyond them by disclosing the append/preserve semantics ('preserving its ID and revision history') and the concurrency-protection requirement of reading the current revision first, though it says nothing about permissions or error behavior.

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

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

Two sentences, no filler. The core purpose is front-loaded and the prerequisite instruction follows immediately.

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, annotations covering the safety profile, and 75% schema coverage across 8 parameters (including nested validity and enum scopes), the description supplies the essentials. It could still note the personal-vs-team scope distinction (team_id) or what the corrected revision returns, but nothing critical is missing.

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

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

Schema description coverage is 75%, so the baseline is 3, but the description meaningfully reinforces two parameters: it enumerates the action modes (correct/reject/retract) and ties expected_revision to a concrete retrieval step. It does not clarify value/validity/team_id semantics, which remain schema-only.

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 names a concrete verb-phrase and resource: saving an explicit user correction, rejection or retraction of a cited person claim. Combined with the title and the mention of claim ID and revision history, an agent can distinguish this mutation pathway from generic siblings like update_person or add_memory.

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

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

It gives a clear usage context (only for an *explicit* user correction/rejection/retraction, reinforced by the schema's 'never invent a correction on their behalf') and a prerequisite workflow step: 'Read its current revision first.' It does not name alternative tools (e.g., memory_save for new facts), so it stops short of full when/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 indicate non-readOnly, non-idempotent, non-destructive hints. The description adds substantial behavioral context beyond that: it explains the @mention linking mechanism, the Team-visible relationship nuance, and the semantics of recommended optional fields (assigned_to, remind_at). It effectively communicates the side effects and constraints of the operation without contradicting any 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 front-loaded with the core purpose, then progressively covers team context, recommendations, and alternative actions. Every sentence adds essential information—there is no filler. The structured flow makes it easy to parse and act on, and the final sentence routes to related tools seamlessly.

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

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

Despite the tool's moderate complexity (6 params, multiple contexts, sibling interactions), the description covers the full invocation surface: what it creates, how to use it in Team vs. personal context, which options are recommended vs. optional, how @mentions work, and how to handle the created action afterward (read/close/edit). The output schema exists, so return values need no explanation. Nothing an agent needs to call it correctly is missing.

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

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

All parameters already have schema descriptions (100% coverage), but the description enriches them meaningfully. It clarifies the relationship between team_id and assigned_to ('Required with assigned_to; connected Team chats supply it automatically'), defines the @mention behavior in content, and marks remind_at as 'RECOMMENDED' with a categorical reason ('Omit only for genuinely open-ended work'). This goes well beyond the schema.

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

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

The description opens with a specific verb+resource: 'Create a follow-up tied to a person — a to-do for the relationship.' It clearly distinguishes this tool from siblings by naming complete_action and update_action for closing and editing, and it gives concrete examples ('send the deck', 'intro to Ana'). The purpose is unmistakable.

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 guidance on when to use this tool and when to use alternatives: 'Read open ones via get_person', 'close them with complete_action or edit them with update_action.' It also covers the Team context condition (when to pass team_id and assigned_to) and recommends when to include certain fields, leaving no ambiguity about the decision process.

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 this is a non-readonly, non-destructive, non-idempotent, closed-world creation call. The description adds genuine behavior beyond that: the description field is REQUIRED and drives matching quality, AI suggestions default to off, proposed people require user confirmation, and the call returns a new list_id. These are useful additions, but deletion/cleanup implications and duplicate-name behavior remain unstated.

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?

Front-loaded with the operation and resource, then the required-description rationale, then optional behaviors, then the return value. It is dense and parenthetical but every sentence carries information; minor redundancy between the description text and schema wording on ai_enabled.

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 brief 'Returns the new list_id' is sufficient rather than required. For a four-parameter creation tool with full schema coverage and clear annotations, the description covers the decision-relevant behavior; only cross-tool placement (list vs view) is left implicit.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, including that name is auto-generated and organization_id omits to a personal list. The description reinforces the two key ones (description as the matching goal, ai_enabled default) but adds little semantic detail the schema does not already carry, so it sits at the baseline.

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?

Opens with a specific verb+resource ('Create a list') and immediately defines the resource as 'a described set of people', with concrete examples ('Seed investors', 'Design candidates'). It is clear against add_to_list/update_list/delete_list, though it never contrasts itself with the adjacent create_view, so full sibling differentiation is not established.

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?

Gives actionable conditions: write a specific description because it is what matching uses, and set ai_enabled=true only if you want proposed people that the user confirms or rejects. It omits guidance on when a list is preferable to a view or when to pass organization_id for team vs personal lists, so there is no explicit when-not.

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 side-effect context beyond annotations: every occurrence creates a new noticed chat and runs the same prompt. It also discloses formatting constraints such as future timestamps, a 60000 ms minimum, and cron-part counts. This is helpful behavioral detail even though the annotations already indicate this is a non-read-only, non-idempotent mutation.

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

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

The description is three sentences with no filler. It front-loads the core purpose and packs the critical schedule encoding rules into the remaining sentences, making it easy to scan and apply.

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 scheduling semantics well and there is an output schema so return values do not need to be explained. Still, it does not address timezone handling, the enabled flag's default behavior, or how the three schedule kinds interact with timezone, which are meaningful gaps for a scheduled-task creation 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 only 17% schema description coverage, the description must compensate, and it does for the most complex parameter: schedule_value. It precisely explains ISO timestamps for 'at', milliseconds for 'every', and 5-6 part cron expressions for 'cron'. However, timezone and enabled parameters receive no semantic guidance, leaving a small but 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 clearly states the tool creates a recurring scheduled task and specifies that each occurrence runs the same prompt in a new noticed chat, distinguishing it from update/list/delete siblings. The phrase 'noticed agent work' is somewhat jargon-heavy, which prevents a 5.

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

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

The description implies this tool is for creating recurring scheduled work, but it never explicitly tells the agent when to use this tool versus update_scheduled_task or delete_scheduled_task. The schedule-format guidance is useful but is parameter-level guidance, not tool-selection 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 provide only false hints (readOnlyHint, idempotentHint, destructiveHint), so the description carries most of the behavioral disclosure burden. It states the view is 'saved' and 'live', implying persistence and real-time effects, but does not mention uniqueness constraints, overwrite behavior, permission requirements, or side effects. This is adequate but not comprehensive for a creation tool.

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

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

Two sentences with no fluff. The primary purpose is front-loaded in the first sentence, and the second sentence enumerates the definition's components without redundancy. Every word contributes value, making it highly efficient for an agent to parse.

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

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

Given the tool's complexity (nested definition object) and that an output schema exists (so return values are handled separately), the description covers the key aspects of what the view is and what it contains. It does not detail prerequisites like team membership or naming rules, but these are partially addressed by the schema (e.g., name optional). The description is nearly complete for an agent to understand the tool's role, though a mention of when team vs personal is chosen could add clarity.

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 75% (below the high threshold), so the description should add meaning beyond the schema. It does: it lists the components of the 'definition' object (search, filters, sort, Team-member filters, relationship types, visible columns) and clarifies 'personal or Team network' for organization_id. This gives the agent a conceptual map of what the definition parameter contains, supplementing the schema's structural detail.

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

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

The description begins with a specific verb ('Create') and a clear resource ('saved live View'), then scopes it to 'personal or Team network'. It distinguishes this from sibling tools like update_view, delete_view, and get_view, making the tool's role unambiguous. The enumeration of what the definition stores further clarifies its purpose without ambiguity.

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 verb 'Create' and the context of a 'saved live View' clearly indicate this is for creating new views, while siblings like update_view and delete_view exist for modifications and removals. However, the description does not explicitly mention alternatives or state when not to use this tool, leaving the differentiation largely 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?

Annotations already declare destructiveHint=true, but the description adds critical nuance: it removes the row outright and does NOT stamp a completion, contrasting with complete_action. This behavioral detail goes beyond the annotations and prevents misuse.

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 four sentences are concise, front-load the core action, and each serves a distinct purpose: definition, irreversibility, alternative, and ID source. No fluff 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?

For a single-parameter destructive tool with an output schema, the description covers all necessary information: what it does, when to use, how to obtain the ID, and the alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, and the schema's description for action_id already includes the source (get_person → relationship.actions or list_actions). The tool description repeats this exactly without adding new semantic information, so it adds no value beyond the schema.

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

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

The description clearly states the tool performs a permanent delete of an action, specifying the resource and operation. It distinguishes from complete_action by noting it's for actions that should not exist, making its purpose unambiguous even among 40+ sibling tools.

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

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

It explicitly tells the agent when to use this tool (mistake, duplicate, irrelevant) and when not to (if follow-up happened, use complete_action). It also provides the source for action_id, giving complete actionable 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 already declare destructiveHint=true and readOnlyHint=false. The description adds meaningful context: it deletes 'its membership/suggestion ledger' and explicitly states 'People remain in the network'. This goes beyond the annotations by explaining what exactly is destroyed and what is preserved. No contradiction with annotations (both indicate a write/destructive 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 three short sentences: purpose, key side-effect, and identification method. It is front-loaded with the primary action, then adds crucial non-destructive context, then parameter guidance. No filler words; 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 aspects for a delete operation: what is deleted, what is preserved, and how to identify the target. It does not mention any prerequisites like permissions or confirmation, but given the annotations already flag destructive behavior and the tool has an output schema, this is sufficient. It could have mentioned alternatives but that is not necessary for correct invocation.

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

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

Schema coverage is 100% and each parameter already has a description. The description adds the instruction 'unambiguous list_name', which is a useful semantic constraint not present in the schema (the schema only says 'matched case-insensitively'). It also reinforces the OR relationship between the two parameters. This adds value beyond the schema, so a score above baseline is warranted.

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

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

The description states a specific verb ('delete') and resource ('list'), and clarifies the scope: 'its membership/suggestion ledger'. This distinguishes it from other delete tools like delete_action and delete_view. It also clarifies that 'People remain in the network', which differentiates from deleting people. The purpose is unambiguous and distinct from 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 useful context for when to use this tool: to delete a list and its ledger, while noting that people are not removed. However, it does not explicitly mention alternatives like remove_from_list for just removing a member, or reject_list_suggestion for discarding a suggestion. It implies the use case but does not explicitly route away from those alternatives. Still, it provides enough context for an agent to understand the intent.

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 flag destructiveHint:true, but the description adds important context that the deletion is permanent and that run history is also destroyed. This goes beyond what annotations alone convey and is consistent with idempotentHint: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?

Two short sentences with no wasted words. The core action is front-loaded, and the alternative usage is provided in a compact second sentence.

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 one-parameter destructive tool with annotations and an output schema, the description covers the essential facts: action, permanence, destroyed run history, and the pause alternative. The unexplained 'noticed' terminology and unstated id semantics are minor gaps, but the overall context is sufficient for safe invocation.

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

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

Schema description coverage is 0%, so the description needed to explain the id parameter, but it never does. The agent must infer from the tool name that id identifies the scheduled task. The single obviously named parameter mitigates the gap, but the description still fails to explicitly add meaning beyond the schema.

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

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

The description states a specific action ('Permanently delete') on a specific resource ('one noticed agent task') and its run history, which clearly conveys what the tool does. It also distinguishes itself from update_scheduled_task by contrasting deletion with pausing. The unusual wording 'noticed agent task' is a minor blemish but does not obscure the core purpose.

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

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

The description explicitly says to use update_scheduled_task with enabled:false when the goal is to pause rather than delete. This gives the agent a clear routing rule between sibling tools and specifies when not to invoke this tool.

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

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

The description clarifies that the operation is non-cascading and permanent, which is critical behavioral information beyond what the annotations provide. However, it doesn't mention failure cases, return behavior, or idempotency, which would be relevant for a destructive 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?

Two short, dense sentences with minimal fluff. Every word contributes to the meaning, and the key qualifiers (typo: 'only') are 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?

For a simple two-parameter destructive operation, the description covers the essential context needed to understand its scope and side effects. A couple of minor aspects (e.g., what happens on success, idempotency) are already covered by the presence of an output schema and the annotations, so they aren't critical 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 description doesn't add to the parameter-level descriptions already present in the schema, but the schema is 100% complete with descriptions like "The View id. Pass this OR view_name." and "The View name, matched case-insensitively. Pass this OR view_id." The description is largely redundant with the schema, so it adds no new parameter-level context.

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?

"Permanently delete a Saved View" provides an explicit, specific verb and resource, going beyond the title and generic name. It clearly communicates the destructive nature and the object of the operation.

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 clarifies the scope of the deletion ("only the saved definition"), but it doesn't explicitly contrast with sibling operations like update_view, create_view, or get_view. It lacks explicit 'use when' or 'use instead of' guidance, relying on the reader to infer when to choose this tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral nuance: dismissal is a soft reject, it does NOT assert the two are different people, and the system may re-propose the pair later. This goes beyond what annotations 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?

Three sentences, no filler, purpose front-loaded. The first sentence states action and effect; the second adds the key behavioral caveat; the third covers identification methods and the alternative. 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?

With five optional parameters and no required fields in the schema, the description correctly explains the mutually exclusive identification methods and the review-queue scenario. It gives enough context for the soft-reject behavior and names the permanent alternative. A minor gap is not explicitly referencing accept_identity_match, but the output schema and sibling list help fill that.

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

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

Schema coverage is 100% and each parameter has a description, but the description adds the crucial grouping logic: one of candidate_id, person_a+person_b, or profile_a+profile_b identifies the match, with profile pairs specifically tied to the review-queue row. This compensates for the schema's misleading all-optional appearance.

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 ('Dismiss'), a specific resource ('PENDING identity match'), and the immediate effect ('stops surfacing'). It also characterizes the action as a SOFT reject and explicitly contrasts it with mark_different_people, making its purpose distinguishable from sibling tools.

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

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

The description explicitly names mark_different_people as the correct alternative for permanent rejection and explains when to use the profile_a+profile_b form (the email→person queue). It does not explicitly mention accept_identity_match as the opposite action, but the sibling name and the 'dismiss' verb make the distinction reasonably clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that — results are 'resumable' and enrichment is 'paid' — but says nothing about auth requirements, rate limits, or what a partial/in-flight outcome looks like.

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 dense sentence that front-loads the verb and resource, with the cost-avoidance rationale trailing. Every clause earns its place; nothing is padded.

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 values need not be described, and annotations cover safety. However, for a 4-parameter tool with 0% schema coverage, the unexplained scope/team_id pair is a real gap an agent could stumble on.

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 carries the full burden. It conveys the meaning of person_ids ('per-person', '1–35-person') and batch_id ('batch'), but leaves scope (the only enum, own vs team) and team_id completely unexplained in both schema and 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?

States a specific verb ('Read') and resource ('resumable, per-person enrichment outcomes ... for a ... batch'), which is far more precise than a bare 'get status'. It implicitly contrasts with enrich_person (the paid work) but never names a sibling to differentiate explicitly, so it stops short of a 5.

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

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

The phrase 'before repeating any paid work' gives a concrete when-to-use cue: call this to avoid re-paying for enrichment already done. It does not name enrich_person or search_enrichment_web as the alternatives it routes away from, so there is no 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?

The annotations already state this is a non-read-only, non-destructive, idempotent operation, and the description's 'missing or updated details' is consistent with that safety profile. However, it does not disclose key behaviors visible in the schema: creating a new relationship via new_person, duplicate confirmation handling, or resumable batch enrichment.

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 definition is a single front-loaded sentence with no filler. It states the action and target immediately, though its brevity contributes to gaps elsewhere.

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

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

For a tool with seven parameters, nested new_person input, team scoping, duplicate confirmation, and batch resumability, the description is quite thin. The rich schema and output schema mitigate this, but the description still does not help an agent distinguish this operation from update_person or understand its creation side effect.

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

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

Schema description coverage is 100%, so parameter meanings are already well documented in the input schema. The description adds no parameter-specific meaning beyond the schema, which is appropriate but not value-adding for this dimension.

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 gives a specific verb ('Enrich') and resource ('a person in your noticed network') and narrows the outcome to missing or updated professional details. It is understandable without opening the schema, though it does not explicitly distinguish itself from siblings like update_person or research_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?

There is no explicit when-to-use guidance or comparison to alternatives such as update_person, research_person, or add_to_network. The phrase 'in your noticed network' implies an existing relationship, but the agent is left to infer when enrichment is the right choice.

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

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

The description discloses important behavioral details beyond the annotations: it returns metadata only, and it warns that a null GitHub handle/profileUrl means unknown and should not be derived from the numeric id. This adds value beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, though it does not cover potential rate limits or authentication requirements.

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

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

The description is compact and front-loaded with the primary purpose. Every sentence carries meaningful detail (e.g., the GitHub caveat, the 'metadata only' note), but it is slightly dense. Still, there is no fluff, so it earns a 4.

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 simple (one optional parameter) and has an output schema, which the description does not need to explain. The description covers the key aspects: what is inspected, the special GitHub handling, and the recommended usage. It is sufficiently complete for an agent to call it correctly, though it does not describe the exact output shape (handled by the schema).

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

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

The input schema already fully describes the single optional parameter ('Optional integration source to inspect; omit for all sources.'), and schema coverage is 100%. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: inspecting integration sources and their metadata (labels, connection state, sync cadence, etc.). It distinguishes from sync_connected_source by emphasizing it returns metadata only, but it does not explicitly name sibling tools or contrast with them, so it falls short of a 5.

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

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

The description provides explicit guidance on when to use the tool ('use this before claiming a source is connected or current'), which is clear context for the agent. However, it does not mention when not to use it or suggest alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds behavioral guidance by instructing 'Present the returned link exactly', which tells the agent not to modify or reformat the result. This is meaningful context beyond the annotations, though the term 'noticed' remains ambiguous.

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 zero fluff. The main purpose is front-loaded, followed immediately by the most instructive example and a crisp output-handling directive. 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?

For a 3-parameter tool with a rendered output schema and safety annotations, the description covers the essential decision points: integration vs. MCP, the Wispr Flow special case, and exact presentation of the result. A minor gap is not explaining mcp_url selection behavior, but the schema fully covers that.

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

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

Schema description coverage is 100%, so the schema documents all parameters. The description adds value by giving a concrete example mapping for Wispr Flow (target='integration', source='wispr-flow'), which clarifies how the enum values should be combined, and by implying the returned value is a link to be used as-is.

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 ('Get') and resource ('connection or management experience for an integration or MCP server'), and explicitly differentiates between the two target types. The Wispr Flow example further pins down the exact usage, making the tool's purpose unmistakable and distinct from any sibling tool.

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

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

The description provides clear context on when to use the tool (for retrieving connection/management links) and includes a concrete parameter mapping for Wispr Flow. It does not explicitly state exclusions or alternatives, but no sibling tool appears to overlap with this function, so the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful context that the tool 'replays the server instructions text on demand,' but does not elaborate on response format or potential caching behavior.

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

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

Two concise sentences with no filler. The core action is front-loaded, and the secondary note about when to call is brief and useful.

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 zero-parameter read-only tool with a rich set of annotations and an output schema, the description fully covers what the tool does, what it returns, and when to use it. Nothing essential is missing.

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

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

The tool has zero parameters, so there is no parameter semantics burden. Schema description coverage is 100% and no parameters exist, making the description sufficient without adding parameter detail.

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

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

The description states a specific verb ('Returns') and resource ('this connector's instructions'), and clarifies what the instructions contain ('what noticed is and how to use it'). It is unambiguous and does not overlap with any sibling tool.

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

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

The description directly says 'call anytime to re-read,' which gives clear when-to-use guidance. It does not explicitly name alternatives or exclusions, but none are needed given the tool's self-referential purpose.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: that review_url presence doesn't guarantee reviews are configured, that member_total is the authoritative size (not members.length), and that pagination continues while member_has_more. These details help the agent interpret results 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 five short, focused sentences, each adding distinct value: purpose, return fields, size caveat, pagination, and identifier choice. It is front-loaded with the primary action and contains no filler or redundant statements.

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 single-list retrieval with a full output schema, the description covers all essential calling aspects: identification method, pagination pattern, return field semantics (member_total vs members.length), and the review_url caveat. The output schema handles the return structure, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that list_id and list_name are alternatives (already stated in schema) and that page/page_size drive pagination, but it does not introduce new parameter constraints or syntax. It adds marginal context beyond the schema, but not enough to raise the score above baseline.

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: 'Open one list' and enumerates the returned contents (relevance-ranked members, pending suggestions, rejected_person_ids). It clearly distinguishes itself from list_lists (which lists multiple lists) and from update_list/delete_list (mutating) by implying a read-only single-list operation.

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

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

Provides clear guidance on how to call the tool: identify by list_id or list_name, and paginate with page/page_size while member_has_more. It also gives a caveat about using member_total for size. However, it does not explicitly contrast with sibling tools like get_list_reviews, though mentioning review_url hints at it. Overall, clear usage context without 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: pagination semantics (10 per page, hasMore/memberHasMore), that counts are unfiltered, corrections replace answers, undo removes them, and that list membership is never approval. No contradictions 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 efficient and front-loaded, starting with the core purpose and then adding necessary behavioral details. Each sentence adds value—pagination, counts, and the approval caveat—without redundancy. It is slightly long but appropriately so for the complexity.

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

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

Given that an output schema exists, the description need not detail return values, but it still mentions key returned fields (setupState, reviewerUserId, reviewScope, review_url). It covers pagination and the dual-listing behavior (answers vs eligible memberPersonIds) thoroughly. Minor gaps remain around parameter usage (e.g., list_id vs list_name), but overall it is fairly complete for a read tool with this complexity.

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 parameter meaning. It mentions 'page' in the context of pagination and implies 'answer' as a filter, but does not explain the roles of list_id vs list_name, nor the exact filtering behavior of the 'answer' parameter. Given the 0% coverage, the description does not sufficiently compensate.

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

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

The description clearly states the tool reads the authenticated user's latest review answers and counts, using a specific verb (Read) and resource (list reviews). It distinguishes itself from sibling tools like configure_list_review by emphasizing 'read only' and 'reviewScope=self', making it unambiguous which tool to use for reading own reviews.

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

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

The description provides context on how to use the tool (pagination, verifying batches) but does not explicitly contrast it with alternatives like configure_list_review or list_lists. It implies when to use it (to read reviews) but lacks explicit 'use this instead of X' guidance, leaving some inference to the agent.

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 cover safety (readOnly, idempotent, non-destructive) and closed-world; the description goes well beyond them, disclosing the default versus 'extras' payload split, that legacy collections preview up to 12 items, that cursors/limit are needed for complete reads, that section metadata distinguishes missing/unrequested/failed, and that an empty field means not recorded rather than false. It also explains team pooling and consent attribution and which consenting teammates' data is merged.

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?

It is front-loaded with what the default read returns, which is good, but the body runs long and spends many sentences documenting individual output fields (contact, relationship, memories, relationship_type_evidence) that an existing output schema already carries. That bulk makes it harder to scan for the actionable decisions: which scope, which include, how to page.

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 an 8-parameter, nested read with team pooling, sectioned paging and an output schema, the description covers defaults, paging behavior, empty-value semantics and scope semantics. Nothing material needed to call it correctly is missing.

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

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

Schema coverage is 100%, so a 3 is the baseline, but the description adds meaning the schema does not: compared_to is resolved against 'current canonical values', the team scope is pooled across every team unless team_id narrows it, and it warns to read contact.emails rather than the single top-level email. The include:'extras' restatement largely duplicates the schema, keeping this below a 5.

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 resource and its scope: 'One person's unified knowledge and compact legacy record', then enumerates the default payload (profile, current role, relationship context). It implicitly distinguishes itself from search_people by naming it as the source of person_id and from list-style siblings by emphasizing a single-person read. It stops short of a crisp verb-first statement and never explicitly contrasts with my_profile or 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?

Routing conditions are given for the main branches: person_id:'me' for yourself, scope:'team' only for a person from a team search_people hit, include:'extras'/'all' for work history, and compared_to ignored for team records. It does not state when NOT to use this tool or name an alternative for the same task (e.g., my_profile, research_person), so exclusions are absent.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real value on top by bounding the returned scope (what is deliberately omitted), which the annotations cannot convey. It doesn't discuss permissions or error behavior, keeping it at 4 rather than 5.

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, zero redundancy, with the scope statement front-loaded and the selection rule last where it is most actionable. Every sentence carries distinct 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?

Complexity is low, an output schema exists so return values need no prose, and the description covers purpose, scope exclusions, and the identifier selection rule. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds a constraint the schema does not express: exactly one of the four identifiers must be supplied, and list/view selectors cannot be mixed. That resolves a genuine ambiguity left by the empty required list and absence of a oneOf.

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 verb ("Inspect") and a precisely scoped resource ("general-access and publication state for a List or View"). The wording also implicitly separates it from the mutation siblings set_general_access and set_published, so an agent can pick this for reading without opening a 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 second sentence gives an explicit exclusion set (collaborator grants, invitations, comments), which tells the agent when this tool is NOT the right choice. It stops short of naming the sibling tools that do cover those cases, so the routing guidance is clear but not fully closed.

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 readOnly/idempotent/destructive safe; description adds consent-rule caveat and pagination behavior, which goes beyond annotation baseline. 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?

One tight sentence that front-loads purpose and includes return behavior; zero 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?

Output schema exists, so return details are covered structurally. Description covers execution scope and consent rules. Lacks error cases or prerequisites, but these are not critical for a read-only tool with strong annotations.

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 covers 100% of parameters with descriptive text. Description adds no new parameter-level meaning beyond schema, so baseline 3 is appropriate.

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

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

Clear verb and resource: 'Open a saved View and execute it' — distinct from list/create/update/delete siblings. Mentions live network scope and return type (definition plus paginated matches), establishing a unique purpose.

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

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

States execution context (live personal or Team network) and references consent rules, but does not explicitly contrast with siblings like list_views or say when not to use it. The context is clear enough to infer, but explicit routing is absent.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the meaningful context that this is the canonical voice source and that remembered copies should not be trusted, but it does not disclose additional behavioral details such as return format or potential errors. With annotations covering the core behavior, a mid-score is appropriate.

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

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

The description is two sentences with no filler. The first sentence states what the tool provides and its scope; the second gives clear call timing and an important warning. Every phrase earns its place and the key constraint 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?

For a no-parameter, read-only tool with an output schema and comprehensive annotations, the description is complete. It explains the purpose, scope, timing, application, and authority of the tool, leaving no critical gap 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?

The tool has zero parameters, and the schema description coverage is 100%, so there is nothing for the description to add about parameter meaning. The baseline for zero-parameter tools is 4, and the description appropriately focuses on usage rather than parameters.

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

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

The description clearly identifies the tool as the source of writing-voice rules for outbound messages, intros, follow-ups, and posts. It uses a specific verb ('get') and resource ('canonical writing-voice rules') and distinguishes itself from siblings like get_instructions by emphasizing it is the single source of truth for the user's voice.

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 instructs when to call the tool ('BEFORE drafting') and how to apply the result ('apply strictly'). It also warns against relying on remembered or restated copies, which effectively guides the agent to always use this tool rather than cached knowledge. This is strong usage guidance for an agent.

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/idempotentHint, so the safety profile is covered; the description goes further by disclosing result ordering (soonest remind_at first, undated last), an exclusion rule (snoozed actions are withheld until they resurface), and that team scope is consent-gated and attributed to owners. What it does not cover is failure behavior when consent is missing or how bounded 'limit' truncation is signalled, which keeps it short of a 5.

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?

It is front-loaded with the primary use case and the result shape, then walks parameters in a logical order with no filler sentences. It is dense and long-ish for a list tool, and the team/goal interaction sentence is packed enough to require a second read, which costs it a point.

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 six-parameter, zero-required filtered list tool with a full output schema and complete annotations, the description covers scope selection, narrowing, exclusions, ordering, and the sibling alternative. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds cross-parameter meaning the schema does not: omitting team_id reads every team, and with a Team sweep the goal_id must belong to the Team that owns the Goal. It also clarifies that goal_id filters to confirmed people only, which is a semantic constraint beyond the field's own text.

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 — every open follow-up/action across the whole network — and states the shape of the result (each attached to its person). It explicitly contrasts itself with the sibling get_person, so an agent can separate the network-wide sweep from the per-person read without inspecting either 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?

It gives an explicit when-to-use rule ('use this to sweep all your to-dos ... instead of calling get_person per person') and an explicit when-not with the alternative ('for one person's actions use get_person → relationship.actions'). The scope/team_id/goal_id/undated/person_id paths are each framed as conditional refinements, so the agent knows which knob selects which behavior.

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 cover readOnlyHint=true and idempotentHint=true, so the description isn't needed to establish safety. It adds real behavioral context by disclosing the sort order (newest first), that pending suggestions are included by default, and the shape of the result records. Minor omissions like pagination beyond the limit parameter prevent a 5, but the disclosure is strong.

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 orders information from most to least important: purpose, result fields, parameter usage, then a mental-model summary. The closing quoted question is slightly redundant with the opening sentence but reinforces the tool's intent for an agent doing semantic matching.

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 low-complexity read-only list tool with only 3 optional parameters, an output schema, and full parameter coverage, the description leaves no meaningful gap. Ordering, defaults, filtering, and result content are all specified. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful value beyond the schema. The 'either side' parenthetical reveals non-obvious asymmetric matching semantics for the person parameter, and the status example ('status='pending' for the review queue') maps parameters to a concrete workflow. This is exactly the kind of behavioral nuance a schema alone wouldn't convey.

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

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

The description opens with a specific verb+resource: 'List the cross-source identity matches in your network, newest first' and goes on to detail the exact result fields (linked identities with sources, confidence, reason, status). The read semantics are immediately distinguishable from sibling mutation tools like accept_identity_match, dismiss_identity_match, and suggest_identity_match, so an agent can confidently tell this apart from every sibling.

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

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

The description teaches how to use each filter ('Pass person to scope to one person (matches on either side)') and demonstrates a targeted use case ('status='pending' for the review queue'), plus clarifies the default inclusion of pending suggestions. It does not explicitly name alternatives or state when-not-to-use, but the context for scoping and filtering is unambiguous.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds scope ('the user's') and the lifecycle vocabulary, but says nothing about ordering, pagination default behavior, or whether 'pending' really means all five statuses — a title/description tension worth flagging.

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

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

Two sentences, front-loaded with the resource and its scope, followed by the questions it answers. The parenthetical status list is mild duplication of the schema enum but is cheap and 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?

With an output schema, full parameter coverage, and strong read-only annotations, the definition supplies most of what an agent needs. The remaining gap is the missing link to track_intro and the slight ambiguity between 'pending' and a status filter that includes done/dropped.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema itself; baseline 3 applies. The description only echoes the status vocabulary already in the enum and adds no meaning for connector_person_id or the limit behavior.

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 names a specific resource (the user's introductions) and enumerates what each row carries — who offered, who the connection is to, and lifecycle status. An agent can tell this is a read/list tool, though it never names the natural sibling (track_intro) to distinguish listing from creating/tracking an intro.

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?

Usage is conveyed only indirectly, through the example questions ('what intros am I waiting on?', 'who promised to connect me to someone?'), which imply the right context. There is no explicit when-not guidance and no mention of track_intro as the alternative for creating or advancing an intro.

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 establish a safe, read-only, idempotent operation, while the description adds meaningful scope and result behavior: included list types, excluded Views, membership counts, and pending-suggestion counts. It does not discuss operational details such as pagination, ordering, or freshness, so it is informative rather than exhaustive.

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

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

Two compact sentences front-load scope, exclusions, and returned metadata, then finish with actionable selection guidance. No wording merely restates the tool name or repeats the annotations.

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

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

For a zero-argument, read-only listing operation with an output schema, the description supplies what an agent needs to select and invoke it: scope, exclusions, useful result fields, and the list_id discovery workflow. Detailed return typing can remain in the output schema, so no additional response-format explanation is necessary.

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

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

There are no input parameters, so the empty schema is already complete and warrants the baseline score. The mention of list_id usefully explains the downstream value of the results, although it is not an input parameter requiring further documentation.

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

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

It clearly identifies a listing operation over the user's personal, Team, and shared lists and summarizes the per-list metadata returned. The explicit Views exclusion and list_views pointer distinguish it from a close sibling.

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

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

It gives an explicit entry-point rule—"Start here when the user names a list"—and explains that the practical goal is obtaining list_id. It also provides a concrete alternative by excluding Views and routing those requests to list_views.

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 states it's read-only and idempotent (matching annotations), and describes the output fields (person_id, name, email, any URL already submitted). It doesn't cover edge cases like no results or errors, but the annotation hints and the description together provide adequate transparency.

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

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

The description is reasonably concise but includes some redundancy (e.g., repeating 'no LinkedIn or GitHub' and 'any URL already submitted') and a minor typo ('giving noticed'). It could be tightened without losing clarity, so it's slightly above average but not exceptional.

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 fully explains what the tool returns (rows with specific fields), the criteria for inclusion, and the relationship to add_profile_to_person. Given the absence of an output schema, the description provides sufficient context for an agent to understand the tool's purpose and result. Nothing critical is missing.

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

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

The single 'limit' parameter is described with default and max values, and the schema includes a description. Since schema coverage is 100%, baseline is 3, but the added context about the default and maximum elevates it to 4.

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

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

The description clearly states the tool lists contacts missing a profile, specifies the criteria (email-only, no LinkedIn/GitHub, no pending merge), and explicitly ties it to the add_profile_to_person tool. This distinguishes it from other list tools like list_people or list_identity_matches.

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

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

The description implies usage when you need to find contacts to enrich with profiles, and mentions the companion tool add_profile_to_person. However, it doesn't explicitly discuss when not to use it or contrast with alternative listing tools, though the unique purpose makes the usage context clear.

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

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

Annotations already convey read-only, non-destructive, idempotent behavior. The description adds user scoping and mentions included fields, but does not disclose additional behavioral details such as ordering, pagination, or filtering. This is acceptable but not rich; it stays safely consistent with 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 a single focused sentence that leads with the action and resource, then lists the relevant output attributes. Every part adds value and there is no redundant or filler wording.

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 parameterless, read-only listing tool with an output schema and strong annotations, the description fully covers what the tool does and what it returns. Nothing essential is missing for an agent to select and 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?

There are zero parameters and the schema is empty, so there is little for the description to clarify. The baseline for a parameterless tool is 4, and the description adequately identifies the resource and result contents without needing to explain parameter syntax.

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 ('List') with a clear resource ('the user's noticed agent tasks'), and enumerates the returned fields (timing, enabled state, next and last run, run count). It clearly identifies a read-only listing operation and is distinguishable from sibling create/update/delete task tools.

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

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

The description makes the tool's context clear: list the user's tasks rather than creating, updating, or deleting them. It does not explicitly name alternatives or exclusion conditions, but the operation is unambiguous and the sibling tool set makes the intended use obvious.

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 and idempotentHint. The description adds detail about returning 'saved definition and effective access role', but doesn't mention side effects. It is consistent with annotations, so it adds some but not extensive behavioral info.

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

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

Two sentences that are concise and front-load the main action. The second sentence provides usage guidance, making it efficient.

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

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

The description covers what the tool returns (visible views with definitions and roles) and gives a usage hint. Given no parameters and a simple list operation, it seems complete, though output schema details are not described (but that's not required).

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

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

There are no parameters, so schema coverage is 100% by definition. The description doesn't need to explain parameters, and the baseline of 4 is appropriate.

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

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

States it lists visible personal and Team Views with definitions and access roles, clearly distinguishing from other list_* tools for actions, lists, etc. The verb 'List' and resource 'Views' are specific.

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

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

Explicitly says 'Start here when the user names a View.', which gives a clear when-to-use directive. It implies it's the appropriate first step for viewing operations, though it doesn't contrast with alternatives explicitly.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), but the description adds meaningful behavior beyond them: 'Each call appends a new event' (explains the non-idempotent consequence — duplicates if re-called), the implicit network-insert side effect, and downstream effects on 'recency and relationship strength'. It stops short of describing the response or failure modes, but for a low-risk append tool this is substantial added context.

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

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

Five short sentences, front-loaded with the core action and the required discriminator first, then consequences, then the precondition, then the exclusion last. Nothing is redundant with the schema and no sentence is 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?

With 8 params at full schema coverage, an output schema present, and annotations declaring the safety profile, the remaining burden on the description is purpose, side effects, and sibling routing — all of which it covers. Only the response shape and behavior on invalid person_id are unaddressed, which the output schema partly absorbs.

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

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

Schema description coverage is 100%, so per-parameter semantics are fully carried by the schema itself. The description adds only the framing that `type` is the one thing you must decide and 'everything else is optional detail that defaults sensibly', which is mild but genuine guidance on minimal invocation. Baseline 3 is correct given the schema already documents defaults, enums, and field interactions in depth.

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 verb and resource ('Record a touchpoint'), names the discriminator field (`type` with its three enum values), and explicitly distinguishes itself from the nearest sibling: 'NOT for notes ... use add_memory instead.' An agent can identify and separate this tool from add_note/add_memory without opening a 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?

Gives when-to-use ('Record a touchpoint'), when-not-to-use ('NOT for notes'), and the named alternative ('use add_memory instead'). It also states a precondition-free entry point ('Works on any search_people hit — if they're not in your network yet, they're added first'), so an agent knows it needn't call add_to_network first.

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?

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing that the block is durable (prevents future suggestion or auto-merge), that it is reversible by an admin, and that there is a hard limit of 25 per day per network. Those are exactly the operational facts an agent needs before invoking a destructive tool.

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

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

Front-loads the effect and durability in the first clause, then constraints, then identification modes, then the alternative tool. Every sentence carries distinct information with no restatement of the name or title.

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, non-idempotent-looking action with an output schema, the description covers effect, reversibility, rate limit, and all invocation modes, so nothing an agent needs before calling is missing. The return value is handled by the output schema and need not be described.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the pairing logic the schema only implies per-field: which parameters form an alternative set and which scenario (review-queue row, candidate lookup) each set serves. It does not restate types, but it does clarify the OR structure between the five 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?

States a specific verb and resource ('Mark two records as DIFFERENT people') plus the resulting state ('a durable disconnect'), which no sibling in the list implies. It distinguishes itself from the soft-path sibling dismiss_identity_match and from suggest/accept variants by naming them explicitly.

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?

Gives three mutually exclusive identification routes (candidate_id, person_a + person_b, profile_a + profile_b) with the condition that selects each, including the specific email→person false-positive case. It also names the explicit alternative for 'not now' (dismiss_identity_match), so when-to-use and when-not-to-use are both covered.

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 readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, covering the safety profile. The description agrees with these annotations and adds the slight behavioral note that ids originate from memory_search, but otherwise defers to the structured data, which is acceptable given the richness of 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?

Eleven words communicate exactly what the tool does and where the id originates, with the most important action verb leading. Not a wasted word, and the provenance note 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 single-parameter tool with 100% schema coverage, a comprehensive annotations block, and an output schema, the description fully covers what an agent needs to invoke it correctly. The minimal description is complete for the tool's complexity.

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

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

Schema coverage is 100% and the schema defines the id simply as 'The memory entry id.' The description adds value by signaling that a valid id comes from memory_search results, constraining the parameter's valid domain beyond the schema. This is a small but meaningful enhancement.

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 ('Fetch'), a precise resource ('specific memory entry'), and identifies the lookup key ('by id'). The parenthetical '(from memory_search)' further clarifies both the identity domain and the natural workflow, effectively distinguishing this from siblings like memory_search and memory_save.

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 parenthetical '(from memory_search)' implies the expected workflow—search results yield the id to fetch—but stops short of explicitly stating when to choose this tool over alternatives like memory_search or when not to use it. Usage is indicated rather than spelled out.

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=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing deduplication against existing memories and the fact that `person` writes to a contact record in addition to the global store. It stops short of saying what dedup does on a hit (merge vs. skip) or what the response contains, though an output schema 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?

Three sentences, each earning its place: purpose, dedup behavior, parameter effect, then the sibling routing rule. The differentiator (global store vs. person-scoped alternatives) is front-loaded with zero 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?

Rich annotations, 100% schema coverage, and an output schema mean the description needn't explain return values or parameter formats. What remains — purpose, dedup, dual-write, and sibling routing — is fully addressed for a low-complexity, 4-parameter write 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 100% and each parameter already carries its own description, including the person-attachment semantics. The description restates the `person` dual-write behavior but adds nothing about `category` enumeration or `confidence` scaling beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 verb and resource ('Save a durable fact/preference/decision/commitment to long-term memory') and immediately narrows scope with 'Deduplicates against existing memories' and the dual-write behavior of `person`. An agent can tell it apart from add_note/add_memory without opening either 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?

Explicitly routes the agent away from this tool when the content concerns ONE person, naming both alternatives and the condition that selects each ('the user asked you to remember it' → add_note; 'you worked it out yourself' → add_memory). This is a genuine when/when-not rule, not implied 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the scope of the memory store and its long-term nature; it says nothing about ranking behavior, despite minScore implying similarity scoring, or about how results are ordered. With an output schema present, return values need not be explained, so this is adequate but thin.

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 short sentences with zero filler; the resource scope is front-loaded and the usage trigger follows. Every clause 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 read-only search tool with a fully documented four-parameter schema, rich annotations and an output schema, the description covers what is searched and when to invoke it. The only remaining gap is disambiguation from memory_get and memory_save, which the description leaves to 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 description coverage is 100% and every parameter carries a description plus a default, so the schema does the heavy lifting. The description's enumeration of memory content types loosely hints at what memoryType distinguishes (daily vs curated), but never maps that vocabulary to the enum values. Baseline 3 applies.

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

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

States a specific verb and resource ('Search your long-term memory') and enumerates the content types stored there (facts, decisions, preferences, commitments), which goes beyond restating the name. It implicitly distinguishes itself from memory_get and memory_save by being a query-based lookup, though it never names those siblings explicitly.

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 before answering questions about past context' gives a concrete trigger condition for invocation, which is more than most definitions offer. It stops short of when-not-to-use guidance or of routing the agent to memory_get for direct retrieval versus this similarity search.

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 destructiveHint=true and readOnlyHint=false, but the description adds meaningful behavioral detail: the identifier and its Gmail/Calendar/activity move, both records persist ('the identifier ... off the record ... onto the person'), and it 'won't re-attach' to the old record. It also states reversibility via /logs. This is valuable disclosure beyond the annotations, though it stops short of detailing error conditions or permission requirements.

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

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

The description is a single dense paragraph but every clause earns its place: the action, the side effects, the target options, and the alternative tool. It is front-loaded with the verb ('Move...') and purpose. It could be trimmed slightly, but it avoids redundancy and remains readable for an agent.

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

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

Given the tool's complexity (union-type parameter, nested object, destructive operation, no output schema), the description covers the essential decision points: when to use, what moves, that it's reversible, and what NOT to use it for. It doesn't explicitly cover error cases or the exact behavior if both targets are passed, but those are schema-enforceable. Overall, sufficient for correct invocation.

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

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

All four parameters are well documented in the schema (100% coverage). The description adds practical guidance: refers to get_person for the identifier, marks from_person_id as the 'wrongly attached' record, and explains the to_person_id vs to_new_contact choice. The schema already covers formats, but the description's clarification of the union (either-or) and the get_person hint adds value. Slight overlap with schema prevents a 5.

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 gives a precise verb+resource+outcome: 'Move one identifier ... off the record it's wrongly attached to and onto the person it really belongs to.' It states both the action and the intent (fixing a mis-attachment), distinguishing it from a merge tool. This is unambiguous and actionable.

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 explains when to use (identifier wrongly attached) and when not to (merging two records → use accept_identity_match). It also provides a prerequisite hint (see identifiers via get_person) and the OR-choice between to_person_id and to_new_contact. Clear guidance with a named 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), so the bar is lower. The description adds real behavioral context beyond them: permission-aware scoping, inclusion of onboarding research gathered before external accounts were connected, legacy fields being compact previews, and explicit completeness/indexing state with cursors.

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

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

Three tight sentences, front-loaded with the primary purpose and the get_person relationship. The section/cursor mechanics come second. Minor jargon ('completeness/indexing state') costs a little clarity but no sentence is 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?

An output schema exists, so return values need no explanation here. Given the nested object params (per-section cursors keyed by section name) and the 100% schema coverage, the description supplies the missing conceptual layer — why sections and cursors matter for completeness — making it adequate for invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: legacy fields are previews only, sections must be requested to get full histories, and cursors surface explicit completeness/indexing state. This clarifies why the parameters exist rather than restating their types.

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 the resource precisely as the caller's own profile ('Your complete permission-aware self knowledge') and names the related sibling get_person('me'), noting they share canonical claims. The verb is implicit (read) rather than stated, but an agent can tell what it retrieves and how it relates to get_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?

It gives procedural guidance ('request sections and use cursors for full histories') but never states when to choose my_profile over get_person('me') or any other sibling, nor any exclusions. Usage is implied by the data-relationship note rather than spelled out as a routing rule.

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 this a read-only, idempotent, non-destructive, closed-world read. Beyond that the description discloses behavior the annotations cannot: no paging required, and that team scope returns a pooled distinct total (deduped across teammates) plus each member's own size and consent tier.

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?

Front-loads the core capability, then the team-scope exception, then the routing rule — a sensible order with no filler sentences. It is dense with em-dash clauses and repeats a little of what the schema already states, but every sentence carries information.

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

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

For a two-parameter read tool with an output schema and full annotation coverage, nothing an agent needs is missing: purpose, scope semantics, aggregation caveats, and the alternative tool are all covered.

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

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

Schema coverage is 100%, so the schema already defines both params and the omit-team_id behavior; baseline would be 3. The description still adds meaning — 'distinct total known by ANY teammate' and the consent-tier notion — which clarifies what the pooled number actually represents, though some of this overlaps the schema text.

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 resource (network) and specific output content — total people, breakdowns by source/company, recent vs stale — plus a distinct team-scope mode. It also explicitly separates itself from search_people, so an agent can pick it 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?

Gives an explicit routing rule: use this for overall 'how many…' questions, and use search_people with a role filter for 'how many <role/type>'. It also names the condition that selects the team mode (scope:'team') and what that mode returns instead.

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