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

Annotations already cover safety (destructiveHint=false, idempotentHint=true). The description adds genuinely new behavioral context: no hard delete exists and history is preserved, telling the agent the operation is effectively reversible/retention-preserving.

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 with the action front-loaded and the key caveat parenthesized; every word earns its place.

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

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

Return values need not be explained since an output schema exists, and the operation is simple. However, the meaning/format of the sole required parameter is left ambiguous, which is the main thing an agent needs in order to call 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 single 'name' parameter has 0% schema description coverage, and the description only says 'a note' without clarifying whether name is a title, path, or identifier. It fails to compensate for the undocumented parameter.

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 with a destination: 'Move a note to Archive/'. This is clearly distinct from sibling write/patch/capture operations, though it does not explicitly contrast itself with any named 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 parenthetical 'there is no hard delete; history is kept' implies archive is the way to remove a note, which is useful implied guidance, but it never states when to choose this over write, patch, or other siblings.

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

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

Annotations already declare this is a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so safety is covered. The description adds useful context that the note lands in the Inbox and is intended for later filing, but says nothing about validation, limits, or what happens on failure.

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

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

A single front-loaded sentence with no filler; the destination is stated immediately. It is efficient, though arguably terse enough to leave the parameter layer entirely undocumented.

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 the tool itself is simple (two params, one required). Still, with no annotation-level detail needed and zero parameter documentation, the description leaves the agent guessing about `title` and about how this differs from sibling write tools.

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% for both parameters. The word "note" loosely maps to `text`, but `title` is never mentioned and there is no explanation of length limits, formatting, or whether title is optional in practice. The description does not compensate for the coverage 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 states a concrete action and destination: a quick note placed in the Inbox. That is a specific verb+resource, though it never distinguishes itself from siblings like `write` or `log_interaction`, which could plausibly be used for the same intent.

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?

"To be filed later" implies the scenario for using this over a full write (fast, low-structure capture), but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is left 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 a non-destructive, non-open-world write, and the description adds the genuinely non-obvious side effect that both sides are written with an inverse relation on B — telling the agent one call creates two edges. It still omits duplicate/idempotency behavior and any permission or prerequisite 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?

Two short sentences, zero filler, with the primary action stated first and the side effect immediately after. Every clause 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?

An output schema exists, so return values need no explanation, but for a mutation tool that silently writes a second edge the description says nothing about duplicates, whether both people must already exist (note the `upsert_person` sibling), or invalid relation handling.

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

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

Only `rel` is documented in the schema (33% coverage); `a` and `b` carry no descriptions. The description partially compensates by establishing that a and b are people and that the inverse is applied to B, but it gives no identifier format for a/b and no constraint on rel beyond what the schema already lists.

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 concrete verb+resource ('Record how two people are connected') and implicitly separates itself from the one-directional `link` sibling by stating it writes both directions. It stops short of naming that sibling or any other, so an agent still has to infer the boundary from `link`.

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 when-to-use or when-not-to-use guidance, and no alternative is named even though `link` and `who_knows` sit in the same sibling set and plausibly overlap. The agent must guess whether `connect` or `link` is correct for a given edge.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine value by enumerating what content is returned (CLAUDE.md rules, Home, topic-relevant notes), but says nothing about volume, ranking of 'relevant' notes, or cost of the call.

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

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

A single front-loaded sentence with no filler; the bundle contents are enumerated immediately after the framing purpose.

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, the description need not explain return shape, and it correctly focuses on what gets bundled. For a read-only, single-optional-param tool this is close to sufficient, with only the 'relevance' selection logic 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% and there is only one optional parameter with a documented default, so the schema carries the semantics. The phrase 'notes relevant to a topic' loosely ties the topic param to retrieval relevance, but adds no format or scoping detail 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?

States a specific resource bundle (vault rules/CLAUDE.md, Home, topic-relevant notes) framed as start-of-session context, which is more precise than the bare name 'context'. It distinguishes itself from generic siblings like search/read by being an aggregate bootstrap fetch, though it never names those alternatives 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?

'Start-of-session' implies the usage moment, so an agent can infer this is a bootstrap call rather than an on-demand lookup. However, it gives no explicit when-not guidance and does not name search/read/people_graph as the alternatives for mid-session or targeted retrieval.

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, openWorldHint=false, so the safety profile is known. The description adds useful context that the write targets today's Daily note specifically, but says nothing about ordering, idempotency, or what happens to an existing entry, and does not contradict 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?

A single front-loaded sentence with zero filler. Nothing is padded or redundant — the issue is under-specification, which is penalized elsewhere, not verbosity.

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

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

An output schema exists so return values need no explanation, but for a mutation tool with 0% parameter documentation the description leaves the agent guessing about the section parameter and any preconditions. A sentence covering the default section and the expected entry format would close the gap.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and it does not. The 'section' parameter (default 'Log') is never mentioned, and there is no hint about valid section values or the format of 'entry'.

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 target ('Append an entry to today's Daily note'), which is unambiguous on its own. It does not, however, differentiate from plausible siblings such as write, capture, or log_interaction, leaving the agent to infer which surface to use.

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

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

No when-to-use guidance, no statement of alternatives (write, capture, patch), and no indication of when appending to the Daily note is preferred over logging elsewhere. The only implicit signal is the verb 'append'.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the semantics of the window ('overdue or within N days'), but says nothing about ordering, result caps, or whether overdue and upcoming are interleaved or separated.

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

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

A single front-loaded clause with no filler. It is terse to the point of being a fragment, but nothing in it is wasted.

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

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

An output schema exists, so return-value details need not be repeated, and annotations cover the read-only profile. However, for a query tool the agent still lacks usage routing and the parameter default, so the definition is only minimally viable.

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

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

Schema description coverage is 0%, so the description carries the burden for the single parameter. 'Within N days' does convey that within_days is a day-count window, but it omits the default of 7 and whether the boundary is inclusive, leaving gaps the schema does not fill.

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 (people) and a precise filter condition (follow-up date overdue or within N days), which lets an agent distinguish it from generic siblings like person, search, or people_graph. It lacks an explicit verb, but the retrieval 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?

There is no guidance on when to choose this tool over alternatives such as person, search, or people_graph, and no stated prerequisites. Usage is only implied by the tool name and the 'follow-up' framing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the set of checks performed, which is useful scope context, but says nothing about cost, whether it scans the whole vault, or whether results are cached. With annotations carrying the safety burden, this is adequate but not rich.

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 fragment with zero waste and the scope stated up front. It is appropriately sized for a zero-argument diagnostic tool, though the fragmentary phrasing (no verb) makes it slightly more label than instruction.

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, the description needn't explain return values, and with no parameters there is nothing else to document. Listing the diagnostic categories gives the agent enough to know what it will learn, though it omits any note on how to act on findings or how expensive the scan is.

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 takes zero parameters, so per the rubric the baseline is 4. The description correctly implies a parameterless whole-vault scan rather than a targeted query, which matches the empty 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 names the resource (Vault) and enumerates the exact categories of issues surfaced (missing frontmatter, broken links, orphans, unfiled inbox, stale projects), which is far more specific than a bare 'Health' title and clearly separates it from siblings like search, read, or daily. It is a telegraphic noun phrase rather than a verb+resource statement, but the scope 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?

There is no when-to-use guidance: nothing says whether to run this before a cleanup pass, on a schedule, or instead of the sibling 'archive' tool. No alternatives or exclusion conditions are named, so the agent must infer the trigger condition entirely.

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-destructive, closed-world write operation. The description usefully adds where the side effect lands (a 'Related' section) and implies bidirectionality ('to each other'), but says nothing about idempotency, duplicate-link handling, or behavior when a note is missing.

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

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

A single front-loaded sentence with no wasted words; the purpose and effect are stated immediately. It is arguably too terse for a 3-parameter tool, but that shortfall is captured under contextual completeness rather than structure.

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, and annotations cover the safety profile. But with 3 parameters at 0% schema coverage, an unexplained optional 'note' argument, and opaque 'a'/'b' identifiers, the definition is not complete enough for reliable invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It implies 'a' and 'b' are the two notes but never states their format (title, path, or ID), and the optional 'note' parameter is left completely unexplained, which is the highest-value 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?

States a specific verb (Link) and resource (two notes) plus the effect location ('Related' section), which is more than a restatement of the title. However it does not distinguish itself from the sibling 'connect', so an agent cannot tell which linking tool applies to notes vs. people/entities.

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 when-to-use guidance, no prerequisites (e.g., both notes must already exist), and no mention of the 'connect' sibling as an alternative. The agent must infer usage entirely from the name.

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

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

Annotations declare a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real value on top by disclosing exactly which notes get written: a meeting note, a per-attendee Log line, a last_contact update, and the Daily note. That multi-location write behavior is not derivable from the annotations. It does not cover failure modes, ordering, or permission requirements, keeping it below 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?

A single front-loaded sentence that packs the core action and all side effects with no filler. It is appropriately sized for the operation. The compressed list form is dense but readable, which is slightly less scannable than a structured enumeration.

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 the side-effect list covers the most important behavioral fact. However, for an 11-parameter tool with 45% schema coverage, the description leaves most inputs unexplained, which is a meaningful gap for correct invocation.

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

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

Schema description coverage is only 45% across 11 parameters, so the description needs to compensate and largely does not. The mention of 'Meeting note' loosely maps to the meeting_note flag, but date, title, orgs, channel, projects, decisions, follow_ups, and follow_up_date receive no explanation in the description. Most of the parameter surface remains unexplained.

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

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

The description states a specific verb and resource ('Log a conversation') and enumerates the concrete artifacts it produces: a Meeting note, a line in each attendee's Log, last_contact, and the Daily note. An agent immediately understands the scope of the operation. It stops short of naming a sibling alternative (e.g., capture or write), so it does not fully differentiate itself from the rest of the toolset.

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 and no mention of alternatives such as capture or write, both of which appear in the sibling list. The reader must infer from the side effects alone that this is the right tool for recording a meeting or exchange. No prerequisites, exclusions, or routing conditions are given.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful behavioral detail by naming the three edit modes and noting that append may target a section, but it does not explain failure conditions (e.g. what happens when 'find' is absent or ambiguous) or the resulting note state. Adequate but not rich 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?

A single tight sentence that leads with the verb and resource, then enumerates modes in parentheses. No redundancy and nothing wasted.

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

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

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. Still, for a mutation tool with six parameters the description omits error semantics (the 'find' must occur exactly once) and any routing against siblings, leaving moderate gaps.

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

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

Schema coverage is 67%, and the description maps its modes onto parameters (append, section, replace/find, set_meta frontmatter). This adds some meaning, but the mapping is loose and the description never clarifies the interplay between 'find' and 'replace'. It sits at the baseline for a mid-coverage 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?

States a specific verb and resource ('edit an existing note') and enumerates the three operating modes (append, replace exact text, set frontmatter), so the agent knows exactly what the tool does. It does not explicitly distinguish itself from the 'write' or 'capture' siblings, which keeps it 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 'edit an existing note' implicitly signals this is for modifying rather than creating content, which loosely separates it from write/capture. However, there is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer routing from sibling names alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only that the result contains nodes and edges, which the output schema already conveys, and says nothing about graph size, traversal depth, or empty-result behavior for what could be a large unbounded structure.

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 compact sentence, front-loaded with the resource and followed by the optional filters. It is well sized, though the brevity is partly under-specification rather than genuine economy.

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 explained, but for a zero-required-parameter graph query with 0% schema coverage the description leaves the agent without filter semantics or selection guidance. Against 17 siblings in the same domain, this is thin.

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 two undocumented parameters. It merely echoes the parameter names ('filtered by org or context') without saying what an org identifier looks like, what a context refers to, or what happens when both are supplied or omitted.

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 the resource (people graph) and even its shape (nodes and connection edges), which is more than a bare title restatement. However it uses a noun phrase with no verb, so it is ambiguous whether it fetches, builds, or renders the graph, and it does nothing to separate it from siblings like person, who_knows, or connect.

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 only guidance is 'optionally filtered by org or context', which describes a capability rather than when to choose this tool. With siblings such as person, who_knows, and search in the same domain, there is no statement of when this graph view beats a single-person lookup or a 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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by disclosing the aggregation breadth (profile/org/connections/log/meetings/mentions) an agent would not know from the schema. It omits any note on auth scope, latency, or size of the payload.

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

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

A single front-loaded sentence with a colon-delimited inventory of returned facets; every word earns its place and there is no filler.

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

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

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. However, for a broad aggregation tool sharing a namespace with upsert_person and who_knows, the absence of routing guidance and name-semantics detail leaves clear gaps.

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

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

The single parameter 'name' has 0% schema description coverage and no description text, so the tool definition leaves it entirely unspecified — identifier format, disambiguation for duplicate names, or whether it accepts an email/id. The description, which never mentions the parameter, does nothing to 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 names a specific resource (a person) and enumerates exactly what the tool surfaces: profile, org, connections, recent log, meetings, mentions. That is a clear, distinguishable retrieval purpose, but it does not differentiate from overlapping siblings such as people_graph, who_knows, or context.

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

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

There is no when-to-use guidance and no mention of alternatives, despite 17 siblings with clear overlap (people_graph, who_knows, log_interaction, upsert_person). The agent must infer that 'everything about a person' means a broad read rather than the narrower sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds only that the payload includes frontmatter and body, which is modest additional context; it says nothing about error handling for unresolvable names.

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

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

A single front-loaded sentence with no filler; every clause (count, resource, returned fields) 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?

With an output schema defining return values and annotations covering the read-only profile, the description needs little more. It is adequate, though it omits any mention of resolution failures for unknown names or aliases.

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

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

Only one parameter, and the schema documents it fully (names, aliases, or vault paths) at 100% coverage. The description's 'one or more' loosely mirrors the schema's array/maxItems=20 but adds no real semantics beyond the schema.

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

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

States a specific verb (read) and resource (notes), plus scope (one or more) and what is returned (frontmatter + body). It does not, however, distinguish itself from the 'search' sibling, which an agent might otherwise reach for when it wants filtered retrieval.

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

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

There is no guidance on when to use this versus 'search' or 'context', nor any note about behavior for missing or ambiguous names. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully discloses that matching spans names, frontmatter and content, but says nothing about ranking, result ordering, or how the default limit of 10 behaves.

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 well-formed sentence with the resource and search scope front-loaded and no filler. It is efficient, though it has no structure to speak of beyond the one clause.

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. However, with 25% parameter coverage and no usage routing, an agent is left guessing about the tag/limit filters and when this tool beats its siblings.

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

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

Schema description coverage is only 25%: `type` is documented in the schema, while `tag`, `limit`, and `query` are bare. The description does not compensate by explaining tag syntax, whether tag/type combine with the query, or the limit's effect on results.

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 (search) and resource (notes) plus the fields scanned (names, frontmatter, content), so the agent knows exactly what is being matched. It does not differentiate itself from siblings like `read` or `context`, which is the only thing keeping it from 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?

There is no guidance on when to choose `search` over `read`, `context`, or `people_graph`, nor any stated preconditions. The keyword-search framing implies a full-text lookup, but the agent must infer that itself.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so safety is partly covered; the description goes beyond them by disclosing dedup behavior ("Matches existing names and aliases to avoid duplicates") and a data-handling restriction for email/phone. It stops short of explaining what happens when a match is ambiguous or how unspecified fields behave on update.

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

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

Three short sentences with zero filler; the core create/update purpose is front-loaded, followed by dedup behavior and the privacy constraint in order of importance. Every sentence carries information an agent needs.

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 the dedup plus privacy notes are genuinely useful for a mutation tool. However, with 12 params and only a third documented, the description is not complete enough to guide correct invocation of the remaining fields or to explain merge semantics on update.

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 12 parameters and only 33% schema description coverage, the schema leaves most fields undocumented (met, org, role, context, met_via, follow_up, relationship, phone). The description covers only name/aliases matching and the email/phone storage rule, so it does not compensate for the large coverage 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 gives a specific verb pair and resource ("Create or update a person"), so an agent immediately knows this is an upsert operation on a person entity. It does not, however, differentiate itself from ambiguous siblings such as person, write, patch, or capture, leaving the agent to infer which tool handles which mutation.

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 is implied by the upsert semantics, and one meaningful condition is given ("Only store email/phone when the user explicitly gives them to be stored"). But there is no explicit when-to-use/when-not guidance and no sibling is named, so an agent cannot tell whether patch or write is the better route for partial updates.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds essentially no behavioral context beyond the query intent - nothing about how a connection path is computed, depth limits, or what happens when both or neither parameter is supplied.

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 tight sentence fragment with no wasted words, and the dual capability is front-loaded. It is arguably under-specified rather than padded, which is a minor concern for this dimension.

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 needn't be explained, but the tool has zero required parameters and two optional ones whose interaction is ambiguous (org only, target only, both together?). The description should clarify those cases and route to sibling tools; it does neither.

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 only 50%: `target` is documented in the schema but `org` is not. The description partially compensates by implying org = organization to check and target = person to reach, and the 'and/or' wording hints both are optional and combinable, but it adds no format or matching semantics.

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

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

The description names a specific capability in question form: who you know at an org and how you're connected to a person. That is clear enough to distinguish it from a generic search, but it never names a sibling (people_graph, connect, search) or states a concrete verb+resource, so differentiation relies on inference.

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, when-not-to-use, or alternative. The question phrasing implies 'use this to answer network questions,' but with siblings like people_graph and connect present, the agent is left to guess which one applies.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: the create fails atomically on a name conflict rather than overwriting, which is the key operational trait here.

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, front-loaded with the action and followed by the failure condition and fallback. No filler, no restated 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?

An output schema exists so return values need no explanation, and annotations cover safety. However, for a 7-parameter mutation tool with 14% schema coverage, the description leaves several meaningful parameters (tags, type, status, source) entirely undocumented, which is a notable gap.

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

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

Schema description coverage is only 14% — only 'folder' is annotated (with path examples) — while name, body, tags, type, source and status carry no documented meaning anywhere. The description does not compensate, adding no explanation of defaults ('type' defaults to 'note', 'status' to 'active') or what a source reference 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?

States a specific verb+resource ('Create a new note') and immediately distinguishes itself from the sibling tool by naming the alternative ('use patch instead'). An agent can route between write and patch 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 an explicit when-not condition (a note with that name already exists) and names the correct alternative (patch). It does not cover other adjacent siblings like capture or archive, but the primary branching decision is spelled out clearly.

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