ppl - Personal CRM for AI Agents

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it never mentions that a single-use, human-approved approval_id may be required, nor any duplicate-checking behavior despite a contacts.duplicates.check sibling.

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 the trigger front-loaded before the effect. The first is a sentence fragment and the example is slightly loose, but there is no wasted 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?

An output schema exists, so return values need not be described, and only contact_id is required. Still, for an 8-parameter mutation the description omits meaningful context: the approval_id single-use approval flow and duplicate-address handling are both unaddressed.

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 all eight parameters. The description only lightly reinforces two of them (the label mapping to `name`, the street in the example), which is baseline behavior 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?

The description states a specific verb and resource ('Adds it to the contact') and identifies the label concept, so an agent knows this creates an address record on a contact. It does not distinguish itself from the sibling addresses.update for edits, which keeps 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?

It gives a concrete trigger scenario ('When the user gives you someone's address, like "Maya moved to 123 Main St"'), which is real usage context. However it names no alternatives or exclusions — nothing about when to prefer addresses.update, or what to do if the address already exists.

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, so the safety profile is known. The description adds non-annotation context beyond that: the operation 'requires approval by default', which tells the agent an approval flow applies. It stops short of noting irreversibility or cascade effects.

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

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

Two short sentences, zero filler, with the core intent front-loaded before the destructive/approval caveat.

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 annotations cover the safety profile. The description supplies the key behavioral fact (default approval requirement), leaving only minor gaps like irreversibility, which the destructive hint largely covers.

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 both parameters (address_id, approval_id) are documented in the schema itself, so the baseline of 3 applies. The description adds no param-level syntax or format detail beyond that.

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 clear verb+resource (remove an address = delete), and the operation is self-evidently distinct from siblings addresses.create/list/update. It is framed as a usage trigger rather than a direct definition, but the purpose 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?

Gives a trigger condition ('when the user wants an address removed') which implies when to use it, but names no alternatives or exclusions (e.g. use addresses.update to modify rather than remove). Guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and idempotency profile is clear. The description adds only the resource context ('saved addresses, like home or work') and does not describe permissions, pagination, or other behavioral details.

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

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

The description is a single, front-loaded sentence with no wasted words. It gives the usage trigger and concrete examples efficiently.

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

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

For a simple read-only list tool with a single fully documented parameter, complete annotations, and an output schema, the description is largely sufficient. It could explicitly say it lists all saved addresses for the given contact, but the name, title, and schema fill that 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?

The single parameter contact_id has 100% schema description coverage, so the schema already defines it as the contact's API id. The description mentions the contact but adds no further parameter semantics, making the baseline 3 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 identifies the resource clearly: a contact's saved addresses, with examples like home and work. It implies retrieval/list behavior, though it does not explicitly state the verb or distinguish itself from the sibling mutation tools (addresses.create/update/delete).

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 provides a clear usage trigger: 'When you need a contact's saved addresses.' The home/work examples make the context concrete, but there is no explicit when-not guidance or named alternative 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 the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds useful PATCH semantics ('Only the fields you pass are changed') that annotations do not convey, but it omits the notable approval workflow implied by the approval_id parameter (human-approved, single-use request), which is a meaningful behavioral trait for a mutation tool.

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

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

Two terse sentences with no filler, appropriately sized for the tool. Front-loading is slightly off: the key partial-update fact is in the second sentence while the first states a condition.

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 schema covers all parameters. However, for an 8-parameter mutation tool gated by an approval mechanism, the description is thin and does not surface the approval requirement or confirm what happens to unspecified fields beyond a single clause.

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 all 8 parameters and the baseline is 3. The description adds one collective insight (only passed fields are modified) but no per-parameter meaning beyond the schema, so it neither over- nor under-delivers.

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 frames the tool as a condition ('When a saved address changed') rather than stating a clear verb+resource; the actual purpose is carried mostly by the title 'Update Address' and the tool name. The second sentence clarifies it is a partial update, which helps, but the purpose statement itself is weak and does not differentiate from siblings beyond what their names already imply.

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 usage signal is the trigger 'When a saved address changed', which gives minimal context but names no alternatives. There is no guidance on when to use this versus addresses.create (to add a new one) or addresses.delete (to remove one), nor any prerequisites.

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 without the description. The description adds the shape of a suggestion (score, reason, contact, deep link), but an output schema exists, making that detail largely redundant rather than additive.

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 usage trigger and followed by the return shape; nothing is wasted. The second sentence restates what the output schema already defines, which is the only minor 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?

Rich annotations plus an output schema and a fully documented single parameter mean the description only needs to cover the trigger and the nature of the results, which it does. Missing differentiation from 'agent.actions.next' is the one real 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?

There is a single optional parameter and the schema documents it at 100% coverage ('Max actions, 1 to 20 (default 10)'). The description adds nothing about 'limit' or default behavior, which is acceptable at full coverage but earns no credit above 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?

States a specific verb+resource: a ranked list of relationship actions, with concrete examples (reconnect, birthday, overdue tasks). An agent knows exactly what comes back. It never differentiates from the obvious sibling 'agent.actions.next', 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?

Gives a clear trigger condition ('when the user wants a ranked list of relationship actions') backed by three example intents, which is enough to route the call. No exclusions and no named alternative, so it does not reach the explicit when/when-not/alternatives bar 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, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuine behavioral context beyond that: the result is a single ranked action bundled with a reason, a drafted message, and a deep link, which tells the agent this is a composed, opinionated read rather than a raw query.

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 filler, and the usage trigger is front-loaded ahead of the return-value summary. The second sentence is slightly redundant with the output schema but still reads efficiently.

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

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

With an output schema present, the description need not enumerate return fields, and it still summarizes the payload shape (action + reason + drafted message + deep link). Combined with annotations covering the safety profile and zero parameters, the definition is complete enough to invoke correctly; only the sibling routing to agent.actions.list is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline for a parameterless tool is 4. No parameter-level meaning is missing.

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 resource (the single highest-leverage relationship action) with a clear verb implied by 'returns', and the 'single most important' framing implicitly distinguishes it from the list sibling agent.actions.list. It stops short of naming that sibling, so differentiation is inferred 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?

It gives a clear trigger ('When the user asks what they should do next about their relationships') which is genuine usage guidance. However it never names the obvious alternative agent.actions.list or states when this tool is the wrong choice, leaving the relationship between 'next' and 'list' 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?

readOnlyHint=true already declares this is a safe read, and the description's 'Read recent' is consistent with that. It adds some domain context (approval grants no extra OAuth scope, execute only the exact reviewed tool), but that context pertains to the approval workflow generally rather than to what this list call returns or how it 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?

Two short sentences with the read action front-loaded and no padding. The second sentence is somewhat off-topic for a pure list operation, which costs it the top score.

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 no parameters, an output schema present, and a readOnly annotation, the description only needs to frame the read; it mostly does. It still omits how results relate to agent.approvals.request and whether statuses can be filtered, so it is adequate but not fully rounded out.

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, which is the baseline-4 case per the rubric. There are no parameter semantics to describe and the description introduces none incorrectly.

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 verb 'Read' plus the resources 'pending, approved and denied work' make it clear this lists approval requests across all three statuses. It is identifiable as a list tool, but it never explicitly distinguishes itself from its obvious sibling agent.approvals.request, so an agent must infer the read-vs-request split from the names alone.

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 stated when-to-use, no prerequisites, and no named alternative such as agent.approvals.request. The second sentence discusses approval scope and execution semantics, which is guidance about acting on approvals rather than about when to call this list tool, leaving usage 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 only declare readOnlyHint=false, so the description carries most of the burden and does it well: it discloses that this is a gate, that the underlying action must be re-invoked with approval_id, and adds a safety caution ('Never claim execution before the call succeeds'). It does not cover expiry, denial handling, or what the returned approval_id looks like, but the workflow and caution are genuine value-add.

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, zero filler, with the core purpose front-loaded ahead of the follow-up flow and the caution. 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?

An output schema exists, so return-value explanation is unnecessary, and the description fully captures the request-review-then-resubmit loop plus the no-premature-claim rule. It leaves minor gaps around denial/expiry behavior, but nothing an agent needs to invoke 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% and the schema already documents tool_name, arguments (including the approval_id exclusion), and summary. The description reinforces the 'same arguments plus approval_id' contract but adds no format or syntax detail beyond the schema, so the 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: 'Request review of an exact policy-gated MCP action.' This is clearly distinct from siblings like agent.approvals.list or agent.actions.next, which neither request nor gate anything. An agent can identify the tool's role 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?

Provides clear context: use this when an action is policy-gated and needs human review, and explains the follow-up ('After approval call that same tool with the same arguments plus approval_id'). It does not explicitly name alternatives or state when approval is NOT needed, 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 already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds that the result is a single aggregated briefing across four categories, which is useful, but since an output schema exists it needn't detail return values and adds nothing on cost, freshness, or caching for what is presumably an expensive aggregation.

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, zero waste. The trigger condition is front-loaded and the content enumeration follows, so the agent gets the 'when' before the 'what'.

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 tool with a rich output schema and full annotations, the description supplies the trigger and the scope needed to call it correctly. The one material omission is disambiguation from the other briefing/digest siblings, which would be needed to route reliably in this large toolset.

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 there is no parameter semantics to explain; the baseline of 4 applies. The description correctly implies the briefing is unfiltered and scoped to the calling user, with no arguments required.

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 (get one daily briefing) and enumerates its contents: birthdays, fading relationships, open tasks, reminders. That clearly distinguishes it from generic list tools, but it never accounts for the very similar siblings agent.routine.briefing, proximity.briefing.get, or contacts.digest.get, so an agent cannot tell these apart from the text alone.

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 trigger conditions: when the user asks what needs attention today, or at the start of a session where relationships matter, and asserts priority with 'call this first'. However, it offers no when-not guidance and does not name the competing briefing tools as alternatives, which matters given three other 'briefing/digest' 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 readOnlyHint, idempotentHint, non-destructive, closed-world, so the safety profile is covered. The description adds that each insight carries a ready-to-send draft message, which is useful behavioral context. It adds nothing about permissions, rate limits, or ordering beyond that.

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

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

Two compact sentences that front-load the usage trigger before the content examples. The example list is slightly long but each example earns its place by illustrating a distinct insight type.

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 shape, and rich annotations cover safety. The description supplies the missing piece – what kinds of insights and the draft-message payload – making it adequately complete for a one-parameter, zero-required list 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?

There is a single optional 'limit' parameter with 100% schema description coverage, so the schema fully documents it (default 5, max 10). The description contributes nothing about the limit or how results are ordered/selected. Baseline 3 is appropriate when the schema does all the work.

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, together with the title, makes clear the tool surfaces surprising relationship insights, and the concrete examples (birthday plus long silence, fading friendship, new contact) distinguish it from generic list siblings like contacts.timeline.list. However, the body never states an explicit verb+resource ('returns a list of insights') – the purpose is conveyed through scenario framing rather than a direct statement.

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 trigger: 'When the user wants something impressive or delightful about their relationships.' That is a clear condition for invocation. There are no exclusions or named alternatives, so it stops short of a 5.

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

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

Annotations only tell the agent this is not read-only; the description supplies the lease duration (30 minutes), renewal behavior, atomicity, and the meaning of a conflict. That is meaningful behavioral context, though auth/permission requirements and post-expiry semantics are left implicit.

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, no filler, and the core semantics (atomic claim, 30-minute lease) are front-loaded before the renewal and conflict notes.

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 description covers the key lease lifecycle facts. It stops short of explaining expiry/re-claimability and how this interacts with the release/complete 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?

With a single parameter and 100% schema description coverage, the schema already documents item_id as the inbox item id. The description adds nothing about the parameter (e.g. where the id comes from), so the 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 (claim) and resource (work/inbox item) scoped to the authenticated token, and the item_id parameter makes the target unambiguous. It does not, however, distinguish itself from closely related siblings such as agent.inbox.release, agent.inbox.complete, or agent.inbox.progress.

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?

"Call again to renew" gives one piece of usage guidance, and the conflict note implies a contention scenario. But it never says when to prefer this over release/complete/fail, nor what to do when the lease expires or when a claim fails for other reasons.

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 declare readOnlyHint=false and idempotentHint=true; the description goes further by disclosing the active-claim requirement and clarifying that completion does not itself send messages or execute the request. 'Safe to repeat after successful completion' adds nuance to the idempotency hint. It stops short of describing what happens to the item or the resulting state transition.

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

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

Three short sentences, with the core instruction front-loaded and each sentence contributing distinct information (timing, precondition, scope). No padding or redundancy.

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

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

With annotations covering the safety/idempotency profile and an output schema handling return values, the description is nearly complete for a workflow-completion tool. It covers timing, precondition, and scope; only the post-completion state change and relationship to fail/release siblings 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 description coverage is 100%, so both item_id and outcome are already documented in the schema. The description's 'Record the outcome' alludes to the outcome field but adds no format, length, or semantics beyond what the schema already provides. 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?

The description states a specific action – recording the outcome of a completed inbox item – and the timing ('only after doing the requested work') pins it to the completion step of the agent.inbox workflow. It even differentiates scope ('Does not send messages or execute the request itself'), helping separate it from messaging/execution siblings. However, it never explicitly names the 'complete/finalize the item' action matching its own name, leaving a small inference gap.

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 precondition ('Requires your active claim') and a timing cue ('only after doing the requested work'), which implies correct usage. But it names no alternatives among its many siblings (agent.inbox.fail, agent.inbox.release, agent.inbox.progress), so the agent must infer when to complete versus fail or release.

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 declare readOnlyHint=false, so the description carries real weight and delivers: retry-after-backoff behavior, a three-attempt cap before human review, and the safety condition for retryable=false. It does not spell out what the failure record contains or how the human-review escalation surfaces, but the operational retry policy is well disclosed.

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 tight sentences, front-loaded with the core action and then the retry policy. Every sentence carries distinct information; nothing 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 an output schema present, return values need no explanation, and annotations cover the write semantics. The description adds the retry ladder and escalation rule an agent needs to call this correctly. Nothing material 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 every parameter (including the retryable default and retry_after_seconds range) is already documented in the schema. The description restates the retryable=true/false policy rather than adding syntax or constraints, so the 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 ('Record a failure under your active lease') that clearly separates it from agent.inbox.complete and agent.inbox.progress in the same family. An agent can identify the operation 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 concrete when-to-use guidance: set retryable=false when automatic retry would be unsafe or the external send is uncertain. It implies but does not explicitly name the sibling to use for successful completion, so routing guidance is strong but not fully framed against alternatives.

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

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

readOnlyHint already marks this as a safe read, and the description adds genuinely useful behavioral context beyond the annotation: the webhook payload is not authoritative and this call is the source of truth that must precede any action. It does not cover pagination or staleness/caching behavior, hence not 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?

Two tight sentences, front-loaded with what is fetched and followed by the operational rule for using it. No filler or repetition of the 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?

With an output schema present, the description does not need to detail return values, and it correctly focuses on purpose and when to call it. The only gap is that it never indicates how to obtain item_id or how it relates to the sibling inbox read tools, but overall it is 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?

Schema description coverage is 100% for the single item_id parameter, so the schema already carries the parameter meaning. The description adds no syntax, format, or sourcing detail for item_id, so 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 (fetch) and resource (work item), and enumerates what it returns: context, progress, retry time, and actual outcome. It implicitly distinguishes itself from the mutation siblings (claim/complete/fail) by being the authoritative read, but never names a sibling such as agent.inbox.progress or agent.inbox.history to route the agent 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?

The second sentence gives concrete usage context: treat a webhook as a wake-up and fetch this state before acting, which tells the agent when this tool is required. It stops short of naming an alternative or stating when-not to use it, so it is clear context without explicit routing.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely non-structured context: the item states it returns (completed/cancelled/failed) and the interpretive warning 'Never treat approval as execution,' which guards against a real misinterpretation risk. It does not cover ordering, time window, or pagination 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 short sentences, front-loaded with the core action and a tight, high-value caveat. No filler, no redundancy.

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

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

An output schema exists, so return-shape explanation is unnecessary, and readOnlyHint covers the safety profile. Combined with the parameter fully documented in-schema, the definition is nearly complete; only the time semantics of 'recent' remain unaddressed.

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 single limit parameter (1-100) is fully documented in the schema, so the baseline is 3. The description adds nothing about the limit or what 'recent' means in relation to it.

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 (recent work) and narrows scope to completed, cancelled and failed items, which implicitly separates it from the live inbox tools. It stops short of naming any sibling (e.g. agent.inbox.list) explicitly, so differentiation is inferred rather than stated.

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 scope phrase 'completed, cancelled and failed items' implies this is for reviewing past/finished work rather than active claims, which is usable context. However, there is no explicit when-to-use, no named alternative, and no statement of when NOT to use it versus agent.inbox.list or agent.inbox.get.

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?

readOnlyHint already declares the safe-read profile, and the description corroborates rather than contradicts it. It adds genuinely non-structured context: the untrusted-data warning about contact context and request text, which is important prompt-injection guidance for an agent, plus the claimed_until field's relevance.

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 purpose and then the operational caveat. Every clause carries information an agent needs; no padding or restatement of the name.

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. Combined with the readOnly annotation and the untrusted-data caveat, the definition covers what an agent needs for this parameterless list tool, though it leaves the relationship to sibling inbox tools 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?

Zero parameters, so the baseline is 4; the schema is empty and there is nothing for the description to compensate for. The mention of claimed_until refers to a returned field rather than an input, so it does not add parameter meaning.

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

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

States a specific action (read/list) and a specific resource scope: pending human requests and suggested work. An agent can tell it apart from agent.inbox.get or agent.inbox.history in substance. It does not name a sibling 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 'Check claimed_until before claiming' implies a workflow ordering relative to agent.inbox.claim, which is useful implied guidance. However, it never states when to use this tool versus agent.inbox.get, agent.inbox.history, or agent.actions.list, and gives no 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?

The annotation only tells the agent this is not read-only. The description adds real behavioral context beyond that: the call renews the lease for 30 minutes (a significant side effect) and explicitly does not grant approval or execute work. It falls short of stating auth/permission requirements or what a failed/expired lease returns.

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, front-loaded with the core action and the lease scope, then the side effect, then the negative guarantee. No filler and nothing misplaced.

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 the mutation's key side effect (lease renewal) and its limits (no approval/execution) are covered. What's missing for a write tool is prerequisite detail, e.g. what happens if the lease has lapsed.

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 all three parameters are already documented in the schema, including the 'do not include credentials' note and the meaning of the approval flag. The description's 'honest progress' framing adds tone but no syntax or format detail beyond the schema, so 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 (report progress) plus the scoping resource (work under your active lease), and explicitly distinguishes itself from adjacent capabilities by noting it 'does not approve or execute anything'. An agent can separate it from siblings like agent.inbox.complete or agent.approvals.request without opening any 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?

Implies the usage context via 'under your active lease' and the optional approval-waiting flag, which tells the agent this is a mid-work status call. However, it never names an alternative (e.g., when to use this vs agent.inbox.complete, agent.inbox.fail, or agent.inbox.release), so the when-not guidance 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?

With only readOnlyHint=false provided, the description adds meaningful behavioral context: released work becomes available to another agent, attempts remain counted, and release is not a way to bypass retry limits. This is valuable beyond the annotation, though it does not cover permissions, reversibility, or rate-limit behavior in detail.

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 primary action and immediately followed by the critical retry-limit warning. Every sentence earns its place with no repetition or filler.

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

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

The tool has an output schema and full parameter coverage, so the description need not explain return values. It provides the key behavioral caution about retry counting, making it nearly complete, though it could explicitly route users away from complete/fail when release is intended.

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 both item_id and the optional reason field are documented in the schema itself. The description adds no additional parameter meaning or formatting guidance, 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 states a specific verb and resource: 'Release your currently leased work.' It adds the effect 'so another agent may claim it,' which clearly distinguishes this tool from siblings such as agent.inbox.complete or agent.inbox.fail 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?

It gives a clear usage context for currently leased work and explicitly warns against looping releases to evade the retry limit. It stops short of naming alternative sibling tools like complete or fail, so it lacks explicit alternative routing but still provides strong contextual 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 supply only readOnlyHint=false (a write), so the description carries most of the burden and does so well: it discloses that existing pending suggestions are preserved and that it queues rather than executes the actions. These are meaningful behavioral facts beyond the annotation, though permissions or dedup/rate behavior are 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?

Two tight clauses, front-loaded with the primary effect and the retention caveat immediately after. No filler; every sentence adds signal.

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 mutation semantics (queue, do not execute, retain existing) are covered. The definition is essentially complete for a zero-parameter write tool, with only minor gaps around permissions or duplicate 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies for a no-parameter tool.

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

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

The description states a concrete verb (add), a resource (current suggested relationship actions), and a destination (the queue), so an agent knows it populates the inbox queue. It is reasonably distinct from siblings like agent.inbox.list or agent.inbox.get, though it never names an alternative explicitly. The title's 'Refresh' vs the description's 'Add' is reconciled by the body.

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 implied (seed/refresh the suggested-work queue) rather than stated, and no when-not condition or alternative sibling is named. The note that existing pending suggestions are retained gives some operational context for deciding to call it. No explicit routing guidance is provided.

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

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

The readOnlyHint already declares this a safe read, so the description is not carrying the safety profile. It still adds useful context beyond the annotation: the tool only prepares a summary and suggestions, and any resulting write requires its normal scope and approval, which tells the agent this call has no side effects and is not a substitute for the write tools.

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 data sources and closing with the behavioral caveat. Nothing is redundant and every clause carries information an agent can act on.

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 zero parameters, an output schema, and readOnlyHint covering safety, the description only needs to say what is aggregated and does so. The one gap is that it never routes the agent away from the many similar briefing tools in the namespace.

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 no parameters, so there is no parameter semantics for the description to explain. The baseline of 4 applies; nothing is missing that a description could supply.

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

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

The description names a specific aggregation of resources: today's birthdays, due reminders, undated open tasks, scheduled follow-ups and review links, so an agent knows exactly what it retrieves. It does not, however, distinguish this from close siblings such as agent.briefing.get, agent.routine.get, or agent.highlights.list, leaving the agent to infer which briefing to call.

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 'today's' framing implies the tool is for a daily commitment review, and the closing sentence clarifies that the output is suggestions only. But there is no explicit when-to-use guidance and no mention of the alternative briefing/routine tools that sit right beside it in the namespace.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally, yet the description adds real value beyond that: the permission constraint that only the human can change the setting. It does not describe behavior when no routine is configured, but the added auth context is meaningful.

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 tight sentences with no waste; the read purpose is front-loaded and the permission caveat 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?

An output schema exists, so return values needn't be spelled out, and the description still conveys the gist (enabled + local time). For a zero-param read tool with annotations, this is essentially complete, with only minor gaps like behavior when no routine exists.

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 the description carries no parameter burden and the baseline of 4 applies. It correctly describes the two conceptual values returned rather than inventing inputs.

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 ('daily routine') and even names the two fields returned: the enabled flag and the local time. It is immediately distinguishable from write-style siblings, though it does not name any sibling tool (e.g. agent.routine.briefing) to differentiate scope 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?

'Only the human can enable or change it through Settings' tells the agent this is read-only and that mutations belong to the human via Settings, effectively excluding the write path. There is no explicit 'use this when...' trigger, but the read-only context 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?

Beyond the readOnlyHint annotation, it discloses that a bearer credential must be sent, that the URL alone grants no access, that integrity/expiry/message-visibility checks are applied, and that no bytes are returned inline. These are exactly the behavioral facts an agent needs before calling.

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 core action and followed by the auth constraint and the non-return caveat. No sentence is redundant.

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

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

With an output schema present, return-value details need not be explained, and the description covers auth requirements, checks performed, and the no-inline-bytes behavior. Nothing needed to call the tool 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 single attachment_id parameter is fully documented in the schema, so the baseline is 3. The description references an 'authorized attachment descriptor' but adds no format or provenance detail beyond what the schema already states.

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/get) and resource (attachment descriptor + authenticated HTTP download URL), and explicitly clarifies the boundary that no file bytes are returned inline. This cleanly separates it from the write-oriented attachments.upload sibling 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?

The use case is implied clearly (fetch a descriptor/URL for a known attachment_id) and it explains the auth condition for using the URL. However, it names no alternative and gives no explicit when-to-use vs when-not guidance, leaving routing 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?

With only readOnlyHint=false available, the description carries real weight: it discloses MIME-type inspection, the authoritative descriptor returned, the no-send boundary, and that normal recipient permissions and human review still apply. It omits idempotency, deduplication, and retention behavior, keeping 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?

Four tight sentences, front-loaded with the size limit that most affects a calling decision, and every sentence contributes a distinct fact (limit, alternative, MIME handling, side-effect boundary).

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 spelled out, and the description still names the descriptor return. For a two-parameter upload tool the remaining gaps are negligible.

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 both parameters are fully documented in the schema, so the baseline is 3. The description's 2 MB ceiling loosely corroborates the base64 maxLength and restates the canonical-base64 requirement, but adds no new syntax or format 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?

States a specific verb (upload) plus resource (base64 file bytes) with an explicit scope limit and names the alternative route for oversized files. An agent can tell immediately what this tool does and which transport it uses versus the multipart REST path.

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

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

Gives a clear size-based decision rule (up to 2 MB here, 10 MB via authenticated multipart REST) and clarifies that uploading does not send a message. It does not, however, differentiate from the sibling documents.upload, which an agent could reasonably confuse with this one.

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-idempotent, non-destructive write, so the safety profile is covered. The description adds that it records date, notes, and caller direction, but says nothing about the approval_id parameter's human-approval workflow, which is the most notable behavioral trait of this 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 short sentences with the usage trigger front-loaded and an inline example that grounds the intent. No filler, though the example interrupts the flow slightly rather than following the action statement.

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 values need not be described, and the trigger plus recorded fields cover the core use. Still missing are the approval_id workflow context and any routing guidance against the many logging siblings, which a write tool in this dense toolset should provide.

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 all five parameters are already documented in the schema. The description's 'date, notes, and who called whom' maps onto called_at, content, and contact_called but adds no format detail or meaning beyond the schema, so the 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 ('Logs') and resource (a phone call) with the fields recorded, which is clear enough to distinguish it from a generic note or journal entry. It does not explicitly differentiate from siblings like interactions.log or calls.update, but the verb+resource combination 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?

Gives a usable trigger ('when the user tells you about a phone call that happened') with a concrete example, so the agent knows the context. However, it offers no exclusions and never mentions the closely related interactions.log, so an agent cannot tell whether a call should be logged here or there.

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, so the 'This is destructive' clause largely restates structured data. The genuinely additive disclosure is 'requires approval by default', which tells the agent an approval flow (matching the approval_id parameter) gates execution — useful context the annotations do not carry. It stops short of saying what exactly is destroyed or whether the deletion is reversible.

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

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

Two short sentences with zero filler; the destructive/approval caveat is front-loaded immediately after the intent trigger, so an agent can act on it without scanning further.

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 the annotations plus description together cover the safety profile and the approval gate. For a simple two-parameter delete, nothing essential to invoking it correctly is missing; the only soft spot is the vagueness of 'by default'.

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 both parameters are documented in the schema, so the baseline of 3 applies. The description only loosely alludes to the approval mechanism without explaining call_id or approval_id semantics beyond what the schema already states.

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 (removed) and resource (logged call), so an agent knows this deletes a call record rather than modifying it. It is phrased as a user-intent trigger rather than a crisp 'Deletes X' statement, and it does not explicitly contrast with siblings like calls.update, 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?

'When the user wants a logged call removed' gives an implied trigger condition, which is better than nothing. However, it names no alternative (e.g., calls.update for modifying, or whether soft-delete/archive exists) and states no when-not-to-use condition, so guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the id-prerequisite, not behavior such as error handling for a missing/unauthorized call. With annotations carrying the load, a 3 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?

A single front-loaded sentence with no filler; the purpose and prerequisite are packed into one clause. It is efficient, though arguably too sparse to earn a top score.

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. For a one-parameter read tool this is nearly sufficient; only the lack of alternative routing leaves a small 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 100% and there is a single required parameter (call_id), so the schema already documents the input fully. The phrase 'you have its id' reinforces that the id is required but adds no syntax or format meaning. 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: retrieving the details of 'one logged call.' The word 'one' implicitly contrasts with the list operation, so an agent can distinguish it from calls.list without opening the schema. It stops short of explicitly naming siblings, so it does not reach 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?

Gives a use condition ('when you need the details of one logged call and you have its id'), which is a genuine prerequisite. However, it names no alternatives (e.g. calls.list for browsing, calls.update for mutation) and states no exclusions, leaving routing 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without the description. The description adds only the scoping context (overall vs. one contact) and says nothing about ordering, pagination, or result volume beyond what the structured fields carry.

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 short sentence with no filler, and the primary trigger (user wants to see logged phone calls) is front-loaded. It could be tighter by dropping the trailing qualifier, but it is appropriately sized.

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 optional-parameter list tool with an output schema and full annotation coverage, the description is nearly sufficient. The remaining gap is ordering/recency semantics for a call log, which a user asking to "see calls" would likely care about, but nothing required to call the tool 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 both parameters (limit, contact_id) are documented there, so the baseline of 3 applies. The phrase "with one contact" loosely maps to contact_id but adds no syntax, format, or filtering 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?

The description names a specific verb (see) and resource (logged phone calls) and clarifies the two scopes: all calls or calls for one contact. It is readily distinguishable from write siblings like calls.create or calls.delete, though it never contrasts itself with calls.get or contacts.timeline.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?

"When the user wants to see logged phone calls" provides an intent trigger, and "either overall or with one contact" implies the two filter modes. However, it gives no exclusions or alternatives, so an agent cannot tell from the text when calls.get or contacts.timeline.list would be the better pick.

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=false, idempotent=false, destructive=false, and closed-world, so the safety profile is covered by structured data. The description adds nothing beyond that — it does not mention the approval_id single-use requirement, whether the update is reversible, or what happens to unspecified fields.

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 a single short sentence fragment with zero waste, but it is under-specified rather than genuinely concise — brevity here comes at the cost of substance rather than from tight editing of a complete thought.

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 five-parameter mutation tool that consumes a single-use human approval ID, the description is thin: it omits prerequisites, scope of change, and confirmation of behavior. An output schema and rich annotations carry some load, but the agent still lacks enough to call this confidently.

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 all five parameters including the nuanced approval_id and called_at are documented in the schema itself. The description mentions no parameters at all, so it neither compensates nor detracts; 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?

The name and title say 'Update Call', and the description frames the purpose as correcting a logged call's details, so the verb+resource is recoverable. However, the description itself never says it updates an existing call record nor which fields it can change, and it does nothing to distinguish this from calls.create, calls.get, or calls.delete.

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 implied trigger ('when details need correcting'), which is a usable usage cue. But it names no alternatives, no when-not conditions, and no prerequisites such as the call needing to already be logged — an agent must infer the rest from the sibling list.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real behavioral detail beyond them: archiving 'stops new sends immediately' while 'existing records stay readable', and it states the authorization constraint (owners and admins only). It stops short of saying whether the action is reversible/unarchivable.

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, each earning its place: trigger, effect/scope of impact, and permission requirement. Front-loaded with the usage condition before the consequences.

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, annotations cover the safety profile, and the description supplies the trigger, the blast radius, and the auth requirement. An agent has everything needed 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?

Schema description coverage is 100% and the single parameter circle_id is documented as coming 'from list_circles'. The description adds no further meaning about the identifier, so the 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 (archive a circle) and immediately distinguishes it from deletion by explaining that 'existing records stay readable'. No sibling (circles.create/list/update, circles.members.remove) could be confused with this 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?

Explicitly names the trigger condition: 'When the human is done with a circle and wants to close it down.' That is clear when-to-use guidance. It does not name a when-not case or an alternative (e.g. a delete/unarchive path), but none is visible among the 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=false, destructiveHint=true, and idempotentHint=false, so the safety profile is carried structurally. The description adds essentially no behavioral context beyond purpose: no mention of required permissions, uniqueness of name, or what happens to existing members/audiences. The 'private audience or shared space' phrasing mildly gestures at the mode param but discloses nothing actionable.

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 the human-facing trigger front-loaded ahead of the mechanical description. No filler, though the second sentence partially restates the first rather than adding new 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 3-parameter tool with full schema coverage, an output schema, and annotations covering the safety profile, the description is adequate. It does not address the notable destructiveHint=true on a creation tool or any auth/visibility implications, but those are largely carried by structured fields.

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 name, mode, and purpose are already documented in the schema, including the mode default of shared_space. The description's 'private audience or shared space' loosely echoes the mode values but adds no syntax, constraints, or format guidance 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 concrete verb and resource: 'Creates a private audience or shared space', plus the human-facing intent ('a new circle for a group of people'). It is clear what the tool does, but it never distinguishes itself from circles.list, circles.update, or circles.archive, so an agent must infer it is the creation path.

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

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

Gives a trigger condition ('When the human wants a new circle for a group of people, like family or a project team'), which is useful context for when to invoke it. However, it names no alternative tool and states no exclusions or prerequisites, so the routing guidance is only implied.

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

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

Annotations already declare non-readOnly, non-idempotent, destructive behavior, so the description's real contribution is the consent semantics: this does not add the member directly, it sends an invitation that must be accepted. That is important context an agent could otherwise get wrong. It does not mention duplicate-invite behavior, permissions, or rate limits, so not 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?

Two short sentences with zero filler, front-loading the usage trigger before the behavior. Every clause carries information the 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?

With an output schema present, return values need no explanation, and all four parameters are documented. The remaining gap is that the description never clarifies how the invitee is identified given that only circle_id is required, leaving the contact_id/connection_id selection entirely to 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?

Schema description coverage is 100%, with each of the four parameters (note, circle_id, contact_id, connection_id) documented inline, including the contact_id vs. connection_id distinction. The description adds no parameter-level meaning beyond the schema, so the 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?

The description states a concrete verb+resource (creates a consent invitation) and gives the outbound effect ('the invitee must accept'), which is more than a restatement of the name. It does not explicitly differentiate itself from near-neighbors like connections.invite or circles.members.remove, 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?

Provides a clear trigger condition — 'When the human wants to add someone to a circle' — which tells the agent exactly the situation that selects this tool. It offers no when-not guidance and names no alternative sibling, so it misses the top band.

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, idempotentHint, destructiveHint, openWorldHint). The description adds a real behavioral detail beyond them: results are scoped to what is 'visible to the caller,' i.e., access-controlled visibility. Because an output schema exists, it need not explain the return 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?

Two compact sentences with no waste, though the ordering is slightly inverted: the usage trigger ('When you need...') leads before the core purpose is stated, and the title 'List Circles' already implies the 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 low-complexity, parameterless-by-default list tool with full annotation coverage and an output schema, nearly everything an agent needs is present. The only soft spot is the ambiguous 'members / policies' clause, which could leave an agent unsure whether related data comes back from this call.

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

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

There is a single parameter with 100% schema coverage, so the schema already documents the 'limit' parameter and its default of 50. The description adds nothing about pagination or limit behavior, so this is the baseline 3.

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

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

The second sentence ('Lists circles visible to the caller') gives a specific verb and resource that clearly distinguishes it from the create/update/archive/invites siblings. The first sentence muddies the purpose slightly by implying the tool also surfaces 'members' and 'circle policies,' which aren't obviously part of a circles-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?

It opens with a when-to-use trigger ('When you need the human's circles...'), which is genuine usage context, but it names no alternative tool and gives no exclusions or prerequisites. The 'members / policies' phrasing is broad enough to be ambiguous about when a sibling like circles.members.remove context is actually needed.

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 the safety profile is known. The description adds genuinely new context beyond them: the authorization requirement and the fact that removal takes effect immediately, implying no undo or confirmation window.

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, both load-bearing, with the trigger and the authorization constraint front-loaded. Nothing is 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 and annotations cover destructiveness, so the description need not explain return values or reversibility mechanics. It omits failure behavior (non-existent member, insufficient role) but covers what an agent needs to decide and call.

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 all four parameters carry their own guidance, including which siblings supply each id, so the schema does the heavy lifting. The description adds nothing about the three mutually exclusive id alternatives, so the 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?

The description names the resource (circle), the action (remove a member), and the initiating condition. It is clear and specific, though the verb is embedded in a trigger phrase rather than stated as an operation, and it does not explicitly distinguish itself from siblings like circles.update or circles.invites.create.

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

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

It states the trigger ('when the human wants someone removed from a circle') and a hard prerequisite ('only circle owners and admins'). It stops short of naming alternatives or negative cases, e.g. that admins changing roles should use circles.update instead.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation; the description adds the authorization constraint (owner/admin only), which the annotations do not convey. It stops short of explaining partial-vs-full update semantics, which matters given 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 tight sentences with the trigger condition front-loaded and the permission constraint second. Slightly clipped grammar ('When the human wants to...' as an opening fragment) but no wasted content.

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

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

An output schema exists so return values need no explanation, and the schema fully covers the four parameters. The description supplies the trigger and the permission gate; the only unaddressed item is partial-update semantics for a non-idempotent mutation.

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 each parameter is already documented with meaning and allowed values. The description's enumeration of name/description/visibility merely restates the schema fields without adding format or constraint details, matching the baseline for fully documented 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 names the resource (circle) and the specific mutable fields (name, description, visibility), so the agent knows exactly what operation this performs. It does not, however, explicitly distinguish itself from nearby siblings such as circles.archive or circles.create, leaving that separation to be inferred.

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 a clear triggering condition ('When the human wants to rename a circle or change its description or visibility') and a hard prerequisite ('Only circle owners and admins can update'). There is no explicit when-not guidance or named alternative for related operations like archiving.

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

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

The annotations already declare destructiveHint=true, non-idempotent behavior, and closed-world scope. The description adds meaningful operational context: human confirmation, permission checking, linking to a local contact, and the caveat that first messages still require recipient approval. It does not elaborate on what makes the action destructive or whether it is reversible, so it stops 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?

The description is four short sentences, front-loading usage and safety before mechanics and caveats. Every sentence contributes useful information, and the minor informal abbreviation does not impede understanding.

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

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

For a two-parameter mutation with an output schema and safety annotations already present, the description covers the key prerequisites, linking behavior, and post-accept caveat. An agent has enough context 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?

Schema description coverage is 100%, so both parameters are already documented. The description reinforces that invite_token comes from the invitation URL and contact_id represents the inviter locally, but it adds no syntax or constraints 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 names a specific verb and resource: accepting a connection invitation, using invite_token, and linking it to contact_id. It is clearly distinct from connections.invite and connections.list in practice, though it does not explicitly contrast itself with those 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?

It gives a clear condition for use: when the human received a connection invitation and wants to accept it. It also adds an important prerequisite, confirming the person and requested permissions with the human first, but it does not mention alternatives or exclusions.

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

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

Annotations already declare readOnly=false, idempotent=false, and destructive=false. The description adds genuinely useful behavior beyond that: the invitation is single-use, and acceptance happens out-of-band when the recipient opens the shared URL. This meaningfully enriches the non-idempotent, non-destructive profile the annotations only hint at.

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 tight sentences, front-loading the trigger condition before the mechanism. No filler, though the first sentence is phrased as a condition rather than a direct purpose statement, slightly softening the lead.

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 (returning the invite URL is referenced but not required to be explained), and annotations cover the safety profile, so the description only needs to supply the when and the acceptance flow — both present. A brief note on whether an existing connection blocks a re-invite would make it fully complete.

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

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

Schema description coverage is 100%, so both contact_id and the nested capabilities flags are already documented in the schema. The description adds nothing about parameter meaning or the on/ask/off semantics, so the 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 ('Creates a single-use invitation') scoped to connecting with someone on the ppl network for agent-to-agent messaging. An agent can easily distinguish it from siblings like connections.accept or circles.invites.create.

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

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

Gives a clear triggering condition ('When the human wants to connect with someone on the ppl network') and explains the follow-up flow (share URL, other person accepts). It stops short of naming the complementary sibling (connections.accept) that closes the loop, so it's strong but not fully alternative-aware.

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, non-destructive, and closed-world. The description adds that it resolves local contacts to connected people and returns capability summaries, which is useful behavioral context 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?

Two sentences, front-loaded with the usage condition. No wasted words, though the second sentence could be slightly clearer.

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

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

Given the output schema and rich annotations, the description covers purpose, usage context, and key behavior. It omits details like pagination or limit semantics, but those are in 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?

Schema description coverage is 100%, so the schema fully documents the three optional parameters. The description does not add syntax or format details beyond what the schema provides.

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 clear verb+resource: find who the human is connected with and check what a connection allows. Distinguishes from connection actions like accept/invite by focusing on retrieval, but does not explicitly name sibling tools like contacts.list or relationships.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?

Provides clear context: 'When you need to find who the human is connected with ... or check what a connection allows.' It does not state when not to use it or name alternative tools, but the context is sufficient to infer usage.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world semantics, so the burden is lighter. The description adds genuinely useful context the annotations lack: the return value is self-contained HTML (implying embeddable, no external asset fetching needed). It does not mention size, caching, or rendering caveats.

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 tight sentences with no filler. The usage condition leads, which is reasonable, though leading with the action (what it renders) before the when-condition would front-load purpose more effectively.

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 read tool with full annotations and an output schema, the description covers what an agent needs: when to use it and what form the output takes. Only minor gaps remain (no note on how large the HTML is or what happens with a missing contact).

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

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

There is a single required parameter with 100% schema description coverage ('Contact API id.'). The description adds no additional meaning about contact_id - no mention of format, source, or error behavior for unknown ids - so the 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?

The description states the resource (a polished profile card for a person) and the output format (self-contained HTML), so an agent understands this renders a contact card rather than returning raw contact data. It stops short of a crisp verb+resource phrasing like 'Render a profile card for a contact', leaving the connection to contact_id implicit.

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

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

It gives a clear selection condition: use this when presenting a person to a human in a visual format instead of plain text. That implicitly contrasts with contacts.get, but it never names the alternative tool or states when not to use it (e.g., programmatic consumption), so it falls short of explicit routing.

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

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

The annotations already disclose that this is a non-read-only, non-idempotent, non-destructive, closed-world mutation. The description adds little behavioral detail beyond saying it creates a contact with name, email, and phone; it does not mention duplicate risk, approval_id workflow, or conflict handling. There is no contradiction 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 two compact sentences with no wasted text. It front-loads the usage trigger and follows with the creation behavior, and the example adds useful clarity without bloating the definition.

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, annotations cover the safety profile, and the input schema fully documents parameters. The description gives the trigger and basic fields, but it could add context about duplicate checks or approval handling. That gap keeps it from a 5.

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 input schema already documents all five parameters, including approval_id. The description mentions name, email, and phone but omits last_name and approval_id, so it adds little beyond the schema 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: it creates a contact, and the example clarifies this is for a newly introduced person. It does not differentiate itself from nearby siblings such as contacts.update, contacts.import, or contacts.merge, 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?

It gives a clear usage trigger: when the user introduces a new person who should be remembered. It does not say when not to use it or point to alternatives like contacts.duplicates.check for likely duplicates or contacts.update for existing people.

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 non-idempotency, but the description adds material context the annotations cannot: the irreversibility of the operation (with the sole unmerge-after-merge exception) and the human-approval gate that applies by default. Both 'what gets destroyed' and 'auth needs' are disclosed, which is exactly the value a destructive tool description should add.

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 that front-loads the usage trigger and then qualifies irreversibility and approval. No filler or redundancy; every clause carries information an agent needs before invoking.

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

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

With an output schema present, return values need no explanation, and annotations plus the description cover the safety and approval story. The only soft spot is that 'all their data' does not specify the cascade scope for related objects (calls, journal, timeline), leaving an agent to infer the blast radius.

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 contact_id and approval_id are fully documented in the schema, which sets the baseline at 3. The phrase 'requires approval by default' loosely relates to approval_id's optional nature but does not explain its single-use semantics or how to obtain it, so it adds only marginal 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 names a specific verb and resource (remove a contact) and adds destructive scope ('and all their data'), so an agent knows exactly what is being deleted. It does not, however, distinguish itself from adjacent siblings like contacts.merge, contacts.unmerge, or contacts.update beyond naming unmerge as a recovery path rather than an alternative.

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 selection trigger: use only when the user explicitly asks to remove a contact, and notes approval is required by default. No explicit 'when-not' or named alternative is provided, so the routing guidance is solid but not exhaustive.

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 the safety profile is covered. The description adds the aggregation scope (which domains are combined) but nothing about auth needs, rate limits, or freshness beyond what the annotations carry.

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, front-loaded with the 'when' condition and then the contents. No filler, though the enumerated list is somewhat dense.

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

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

With an output schema present and annotations covering safety, the description only needs to convey when to use it and what it aggregates, both of which it does. Nothing critical 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% for the single contact_id parameter, so the schema fully documents it. The description adds no syntax, format, or constraint detail for the parameter, making the baseline 3 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 enumerates the resource's contents (identity, last interaction, open tasks, milestones, highlights, relationship trend), making it clear this is a comprehensive per-person aggregate. It is distinguishable in spirit from contacts.get/contacts.card.get as 'the full picture,' though no sibling is named 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?

'When the user asks about a specific person and you need the full picture' gives a clear trigger condition. It lacks any exclusion or alternative routing (e.g. when to prefer contacts.get or contacts.timeline.list instead), so it stops short of the top score.

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 non-destructive behavior, so the safety profile is covered. The description adds that it returns candidates with match reasons, but it does not add auth needs, rate limits, pagination behavior, or what happens when no candidates are found.

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 efficient sentences with no wasted wording. The usage condition is front-loaded, though the core purpose verb arrives after it rather than in the first 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?

For a read-only lookup with rich annotations and an output schema, the description is nearly adequate. Its main gap is that it does not differentiate this tool from contacts.duplicates.find, which is important context for correct tool selection.

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 all five parameters, even if tersely. The description adds no parameter-level meaning such as which fields drive matching or how limit interacts with candidate ordering, 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?

States a specific verb and resource: checking whether a person already exists before creating a contact. It is clear what the tool does, but it does not distinguish itself from the sibling tool contacts.duplicates.find, so an agent still lacks a clean basis for choosing between the two.

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 when to use it: before creating a new contact. However, it does not name alternatives such as contacts.duplicates.find or state when not to use this tool, so the sibling ambiguity remains 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is covered. The description adds scope ('in the address book') and clarifies this is a pre-merge investigation that itself does not merge, but says nothing about how duplicates are matched or what the limits do.

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

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

One short sentence with zero filler and no repetition of the title. It is a subordinate-clause fragment that leads with the trigger rather than the action verb, which is slightly less front-loaded than ideal but still 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?

For a two-parameter read tool with an output schema and full annotations, the description covers trigger, scope, and pipeline position adequately. The material gap is that it does not resolve the overlap with contacts.duplicates.check, leaving tool selection ambiguous for the most likely confusion pair.

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% with only two simple parameters (contact_id required, limit defaulting to 10), so the schema carries full meaning. The description adds no syntax, format, or edge-case detail for either parameter, which is the baseline 3 case.

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

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

The description states a clear action and resource: find duplicates of a given contact, with match reasons, and situates it before merging. It is understandable on its own, but it never distinguishes itself from the very similar sibling contacts.duplicates.check, so an agent still has to guess which of the two to pick.

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 trigger ('when you suspect a contact has duplicates') and a workflow position ('before merging'), which implies the merge/unmerge siblings are the downstream step. However, it names no alternative and gives no exclusion criteria, so the check-vs-find decision 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 readOnly, idempotent, non-destructive, and closed-world. The description adds no behavioral traits beyond this—it only restates the content that will be returned. With annotations covering the safety profile, this is a minimal contribution.

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

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

The description is a single, front-loaded sentence that states the use condition and the data types. It is appropriately sized and wastes no words.

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

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

An output schema exists and annotations cover safety, so the description need not explain return values or safety behavior. It adequately conveys the tool's scope, though it omits the contact_id requirement, which is fully covered 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?

Schema description coverage is 100% for the single required parameter contact_id. The description does not mention the parameter, but the baseline for high coverage is 3.

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

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

The description identifies the resource ('a contact's typed details') and enumerates field types, but it frames the purpose as a need ('When you need...') rather than a direct action like 'List' or 'Get'. This makes the purpose inferable but not explicit, and it does not differentiate from siblings such as contacts.get or contacts.fields.update.

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 provides a clear when-to-use condition: 'When you need a contact's typed details.' It does not mention when not to use it or name alternative tools, so it lacks explicit routing 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is partially covered. The description adds nothing beyond that, and notably omits any mention of the approval_id governance flow, which is behaviorally significant for a mutation. Thin disclosure for a write 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 short sentence with no waste, and the precondition is front-loaded. It is efficient, though written as a sentence fragment that reads more like a use case than a definition.

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. But for a mutation tool with an approval_id parameter implying a human-approval workflow, the description leaves that process and prerequisite unexplained, falling short of complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, making 3 the baseline. The description adds light color by naming example values ('a new phone number or email') and referencing the field id, but adds no syntax or format 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?

The description frames a scenario ('when one of a contact's details changed') rather than stating what the tool does, so the verb+resource must be inferred from the name/title. It does not differentiate from the sibling contacts.update, which appears to serve a similar role. Adequate but vague.

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 precondition for use ('when a contact's details changed... and you have the field id'), which is implied usage guidance. However, it never mentions alternatives such as contacts.update or contacts.fields.list, nor when not to use it. No explicit routing.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, and closed-world, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond the 'full details' framing and does not clarify what 'full details' includes versus the card/digest siblings. No contradiction with annotations.

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

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

A single, efficient sentence with no redundancy. It is slightly front-loaded on the 'when' clause rather than the 'what', but nothing 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?

With an output schema present (return values need not be explained) and annotations fully covering the safety profile, the description is largely complete for a single-parameter read tool. The residual gap is sibling disambiguation against contacts.card.get and contacts.digest.get.

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 single contact_id parameter is fully documented in the schema. The description adds no syntax, format, or edge-case meaning beyond what the schema already provides, so the 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?

The description states a clear outcome: retrieving the 'full details of one specific contact' identified by API id. The verb is implied via the title/name (Get). It does not, however, differentiate itself from adjacent siblings such as contacts.card.get or contacts.digest.get, which also retrieve per-contact detail views.

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 offers a condition for use ('when you need the full details of one specific contact and you have their API id'), which implies the retrieval use case. But it names no alternatives and gives no exclusions, so an agent cannot tell when to prefer this over contacts.card.get, contacts.digest.get, or contacts.list.

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

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

Adds real behavior beyond the annotations: writes persist immediately and there is a hard cap of 50 per call, which is exactly the kind of limit annotations cannot express. It omits the approval_id human-approval flow, which matters for a non-idempotent mutation, so it is not fully transparent.

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

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

Three short sentences, with the triggering condition front-loaded before the field rules and the size cap. The phrase 'ppl stores it immediately' is slightly ambiguous about what 'ppl' refers to, but 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 no explanation, and the annotations cover the safety profile. What is missing is failure behavior: duplicate handling, partial success, and how the approval_id round-trip is supposed to work for a non-idempotent batch write.

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 both parameters are already documented, and the description largely restates them (first_name required, fact optional). It does add a usage heuristic for 'fact' — supply it when you know something — but says nothing about approval_id, so it stays at 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 and resource (batch import of contacts) and explicitly contrasts with the one-by-one path, so an agent can infer contacts.create is the alternative. It stops short of naming that sibling, which keeps 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?

Gives a concrete trigger: the account is empty and the user describes people conversationally ("my sister Maya, my coworker James"). It also tells the agent to prefer this over repeated single creates. It does not state what to do when the account already has contacts or when the batch exceeds 50.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering the full safety profile. The description adds nothing behavioral on top: no note about the default result cap, pagination, ordering, or whether results are scoped to a workspace. It restates the read-only listing intent without new disclosure.

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 stating the trigger and the optional filter, with no filler. It is efficient, though the typos/abbreviation slightly reduce polish.

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-required-parameter list tool with an output schema and complete parameter documentation, the description covers the essential trigger and filter. The minor gaps (default cap, pagination, result ordering) are low-stakes for a simple read.

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

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

Schema description coverage is 100%, with both 'limit' (default 20) and 'search' (name or email) fully documented, so the baseline is 3. The description's 'filtered by a name or email search string' merely restates the schema's search semantics and adds no syntax or matching-rule 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?

States a specific verb (browse/find/list) and resource (people in their 'ppl'), so the agent knows this returns a collection of contacts. It does not distinguish itself from near-neighbors like contacts.get, contacts.card.get, or contacts.duplicates.find, and the abbreviation 'ppl' is slightly opaque.

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 a trigger condition ('when the user wants to browse or find people') and mentions the optional search filter. However, it names no alternatives or exclusions — e.g., use contacts.get for a single known contact, contacts.duplicates.find for dedup — so the routing guidance is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description usefully adds what actually happens (records move to the primary, then the duplicate is deleted), that it is reversible via unmerge, and that approval is required by default.

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 trigger condition, followed by the effect, then the undo/approval notes. No filler, 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 annotations covering the safety profile and an output schema present, the description supplies the remaining essentials: when to invoke, what mutates, reversibility, and the approval requirement tied to the approval_id parameter. 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 coverage is 100%, so the baseline is 3, but the description adds directional semantics by explaining that records flow to the primary contact and the duplicate is destroyed, which ties contact_id and duplicate_contact_id together conceptually beyond the field labels.

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 (merge) and resource (contacts) and immediately clarifies the scope: combining two contacts that are the same person. An agent can distinguish this from contacts.duplicates.find (detection) and contacts.unmerge (reversal) 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 a clear when-to-use trigger ('two contacts are the same person and the user wants them combined') and names the reversal sibling (unmerge). It does not, however, cross-reference the related contacts.duplicates.check/find tools that would precede a merge decision.

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=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuinely new behavior: it aggregates four record types and returns them newest-first, which the annotations do not convey. It stays silent on pagination depth or result-size behavior, keeping it from 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 states the trigger, the scope, and the ordering with no filler. Nothing could be removed without losing 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, annotations cover the safety profile, and all three parameters are documented, so the description only needs to convey scope and ordering, which it does. The one remaining gap is how to advance through a long history using the before cursor in practice.

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%, with contact_id, limit (default 20, max 100), and before all documented inline. The description adds no parameter-level information such as how to page backwards through history. Baseline 3 is appropriate when the schema carries all parameter meaning.

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

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

The description names a specific resource and scope: the full history with one person, aggregating notes, calls, activities, and tasks in reverse-chronological order. An agent can tell this apart from contacts.get or notes.list by the aggregation breadth. It does not explicitly name the sibling it replaces, 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?

"When the user wants the full history with one person" is an explicit use trigger that maps a user intent to this tool. No when-not conditions or named alternatives (e.g., contacts.get for a profile summary, notes.list for notes only) are given, so an agent must infer the boundaries.

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

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

With destructiveHint=true already declared, the description still adds real value by specifying the exact scope — it restores the most recently merged duplicate and moves back exactly what the merge moved, while records created after the merge stay. This edge-case disclosure goes beyond the annotations, though it doesn't note the single-use approval or irreversibility.

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 deciding scenario, with the behavioral detail following. Slightly dense due to the semicolon clause but 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?

An output schema exists so return values needn't be explained, and both params are covered in-schema. Purpose and behavioral scope are described; only the approval_id single-use semantics are left solely to 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?

Schema description coverage is 100%, so both contact_id and approval_id are already documented. The description adds no meaning beyond that, 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 states a specific action (undo a merge by restoring the most recently merged duplicate and moving records back) that an agent can tell apart from contacts.merge. It's framed as a conditional 'when a merge was a mistake' scenario rather than a direct verb+resource statement, keeping it just 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?

It clearly states the triggering condition: 'When a merge was a mistake and the user wants it undone.' This gives concrete when-to-use context, though it never names the alternative (contacts.merge) or any 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 is non-read-only, non-destructive, non-idempotent and non-open-world, so safety is partly covered. The description adds a meaningful trait beyond that: 'Only the fields you pass are changed,' clarifying this is a patch/partial update rather than a full replace. It does not mention the approval_id workflow, but the schema covers that parameter.

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 tight sentences with no filler, and the value ('only the fields you pass are changed') is placed after the trigger context. The field enumeration is a little long but justified by the parameter count. Structure is front-loaded 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?

An output schema exists, so return values need no explanation, and annotations plus full schema coverage carry the safety and parameter burden. The description covers the trigger and the partial-update behavior, which is enough for correct invocation. A minor gap is that it does not call out the approval_id human-approval path, though the schema documents it.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the omit-to-preserve and null-clears semantics for job, company, and food_preferences. The description's field list largely mirrors the schema rather than adding format or constraint detail. 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?

The description pairs the update action with an enumerated set of mutable fields (name, nickname, email, phone, birthday, job, company, food preferences, tags), making the resource and operation clear. It does not explicitly name sibling tools like contacts.create or contacts.merge, so differentiation is by implication rather than stated. Still, an agent can tell this is a partial record update.

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 trigger phrase 'When something about a contact changed and their record needs updating' gives a genuine when-to-use condition. However, there are no exclusions or alternatives — nothing says when to use contacts.create versus contacts.update, or that duplicate resolution belongs to contacts.merge. The usage context is implied but incomplete for a crowded sibling set.

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