Boardroom Revenue Control

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

Beyond the readOnly/idempotent annotations, it discloses two non-obvious behaviors: the per-click id is deliberately withheld (only existence is reported), and an empty result means no ad-driven conversation was recorded rather than a failure. It also surfaces the required auth scope [marketing:read], which is exactly the kind of context annotations cannot 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?

Three dense, front-loaded sentences with zero filler: purpose first, then the privacy caveat, then the empty-result semantics. Every sentence adds information an agent would otherwise have to guess.

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-optional-parameter read tool with an output schema, the description covers what is returned at a field level, the notable omission (per-click id), the failure-vs-empty distinction, and the required scope. Nothing needed for a correct call is missing.

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

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

Schema description coverage is 100%, so the schema already documents 'limit' and 'since' fully. The description only indirectly references the time window ('in the window') and adds no format or default details beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific mapping (advertisement → conversation) and enumerates the returned fields (ad id, creative, first-touch flag, bound lead), so an agent knows exactly what this resource is. It does not explicitly distinguish itself from siblings like marketing_snapshot or agent_conversations, but the resource is specific enough to be 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?

Usage is only implied: the tool is for finding which ad produced a conversation, and the 'in the window' phrasing hints at the time-scoping parameter. There is no explicit when-to-use/when-not-to-use statement and no routing to an alternative sibling for related questions.

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, so the safety profile is covered. The description adds genuinely new behavioral context: the exact return shape (titles only, no document text) and a hard security boundary ('no credential of any kind is reachable'). No pagination or size limits are disclosed, 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?

Three sentences, front-loaded with the content list and followed by the two most important constraints (missing text, no credentials). The opening sentence is a long enumeration, but every item listed is a distinct payload section an agent would want to know about.

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 existing output schema, and full annotation coverage, the description's only remaining job is to explain scope and limits — which it does decisively by ruling out document text and credentials. Nothing an agent needs before calling it is absent.

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 baseline of 4 applies. The description correctly adds nothing about inputs, since there is nothing to specify.

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

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

States a specific resource (the AI agent's configuration) and enumerates exactly what it contains: mode/persona, working hours, hand-over rules, follow-up cadence, triggers, actions, voice scenarios, and knowledge-document titles. An agent can tell this apart from conversation-oriented siblings like agent_conversations and agent_get_conversation 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?

Explicitly bounds the ask: 'Document text is not returned' and 'reading one whole is a separate, narrower ask,' which tells the agent when this tool is insufficient and that a narrower retrieval exists. It stops short of naming the alternative tool or stating positive when-to-use conditions, so not a full 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?

Beyond the read-only/idempotent annotations, the description discloses two useful behavioral facts: contacts are masked (data redaction) and the call requires the agent:read scope. It does not cover result limits or ordering, but the core behavior is well conveyed.

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, front-loaded sentences with zero filler: the first states what it returns, the second flags masking and required scope. Nothing 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 values need not be explained, and the description covers scope, masking, and fields. The only real gap is routing guidance versus the singular agent_get_conversation sibling.

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%, including the enum-like format for 'since' and the 1–200 bounds on 'limit', so the schema carries parameter meaning. The description adds nothing about parameter semantics, making 3 the correct 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 the resource precisely (conversations the AI agent handled) and enumerates the returned dimensions (intent, language, message count, bound deal), so an agent knows it is a listing of agent-handled conversations. It does not distinguish itself from the sibling agent_get_conversation, which retrieves a single conversation.

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

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

There is no when-to-use guidance, no conditions or exclusions, and no mention of the obvious alternative agent_get_conversation for a specific conversation. The 'since' parameter implies recency filtering but the description never says when this tool is the right choice.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description usefully adds the required authorization scope ([scope: agent:read]), but says nothing about pagination or how the transcript is bounded despite the limit 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 short sentences with zero filler; the resource is described first and the scope tag trails it. 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?

With a full output schema, rich annotations, and 100% parameter coverage, the description only needs to identify the resource and access requirement — both present. Slightly short of complete because it never clarifies its relationship to the listing sibling.

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 conversation_id and limit are fully documented in the schema. The description adds no supplementary meaning about the UUID format or the limit's effect, 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 resource — a single conversation plus its full transcript in both directions — which cleanly separates it from the plural listing sibling agent_conversations. It implies retrieval rather than naming a verb like 'get', but the resource and its content are unmistakable.

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

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

No when-to-use guidance and no mention of alternatives. The obvious sibling agent_conversations is never referenced, so the agent must infer on its own that this tool is for one conversation given an id rather than for listing.

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

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

Goes well beyond the annotations (readOnlyHint, idempotentHint, openWorldHint=false). It discloses PII masking rules, the required crm:read_pii privilege and that it's granted separately, workspace scoping with a not_found cross-workspace behavior, and the required scope crm:read. These are crucial behavioral details the agent cannot infer from structured fields. Annotations already cover the safety profile, but this adds substantial value.

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

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

Two concise sentences that front-load the return contents, then the security and scoping constraints. The scope tag at the end is compact. Could be slightly more front-loaded on PII masking, but no wasted words.

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

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

Given the complexity (PII masking, cross-workspace behavior) and the presence of an output schema (return format doesn't need re-explaining), the description covers everything an agent needs: content, permissions, scoping, and required scope. Complete for correct invocation.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema (UUID of the lead). The description adds context about the lead_id source (scoped to workspace, cross-workspace reads as not_found) and that only one lead is returned. For a one-param tool, baseline is 4 when the description adds some semantic value beyond the schema.

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

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

States a clear verb+resource: retrieves a single lead. It enumerates what is returned (notes, events, stage history, open tasks), which distinguishes it from crm_list_leads. However, it doesn't explicitly contrast itself against sibling tools like crm_list_leads or crm_leads_without_task, preventing 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?

Usage is implied: it's a read-by-id tool, so an agent would naturally use it when it already has a lead_id. But there's no explicit when-to-use versus alternatives (e.g., list_leads for browsing), and no when-not-to-use. Minimum viable context is present, but guidelines are not spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuine behavioral context beyond that: results are sorted by idle time (longest first) and idle days are computed in Asia/Dubai, plus the crm:read scope requirement.

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 plus a scope tag, front-loaded with the filter definition and followed by sort/timezone semantics. No sentence is wasted.

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

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

An output schema exists, so return values needn't be explained. The description fully covers the filter semantics, sort order, timezone, and required scope, leaving nothing an agent needs 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 coverage is 100% and the single 'limit' parameter is fully documented with default, min, and max, so the baseline is 3. The description adds no additional meaning about the parameter.

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

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

States a precise resource subset — 'open leads with no unfinished task against them' — and labels it with an intent-bearing phrase ('the follow-up leak'). This clearly distinguishes it from crm_list_leads, which returns all leads without the missing-task filter.

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 purpose implies the use case (surfacing neglected leads) but never states when to choose this over crm_list_leads or crm_pipeline_overview, nor any exclusions. Usage is left to inference rather than made 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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses three things an agent can't get from structured fields: phone and email are MASKED, results are ordered by newest activity, and `total` is the pre-pagination count. It also states the required auth scope (crm:read). That is material behavioral context layered on top of the annotations.

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

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

Three short sentences, each earning its place: scope+ordering, the masking caveat with the sibling route, and the `total` paging semantics. The critical constraint (masking) is front-loaded rather than buried.

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 existing, the remaining gaps an agent would face are masking, ordering, paging semantics and permissions — and the description covers all four. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so limit, since, stage, pipeline_id and offset are already fully documented with formats, defaults and bounds. The description adds no input-parameter guidance (its only data-semantics note, about `total`, concerns the response), which is exactly 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 establishes the resource and scope ('Leads in this workspace') plus ordering ('newest activity first'), which is enough to distinguish it from crm_get_lead, which it names directly. It does not carry an explicit verb of its own (the 'list' verb lives only in the name/title), so it falls just short of a full 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 an explicit alternative and the condition for choosing it: 'use crm_get_lead for one record when the full contact is genuinely needed.' It also clarifies what question this tool answers via `total`. It does not address the other list-shaped sibling (crm_leads_without_task) or state when not to page here, so guidance is clear 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the required auth scope (crm:read) and discloses the aggregation granularity (per pipeline and per stage with counts and totals), which is real context beyond the structured fields. 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?

Two short sentences and a scope tag, with the payload front-loaded. 'The shape of the funnel' is slightly redundant with the first sentence, but it efficiently conveys the aggregate gestalt without padding.

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

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

For a zero-parameter, read-only, non-destructive tool with an output schema already defining return shape, the description covers purpose, scope and auth requirement. The only material omission is routing guidance relative to overlapping siblings such as dashboard_snapshot or crm_list_leads.

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; there is nothing to document and no gap between schema and description. The description correctly implies an unfiltered global aggregate rather than a parameterized query.

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 (every pipeline and stage) and the payload returned (lead count and total value), which is a precise, non-tautological statement of what the tool produces. It does not explicitly contrast itself with siblings like crm_list_leads or dashboard_snapshot, so it stops short of full sibling differentiation.

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

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

There is no explicit when-to-use or when-not-to-use guidance. 'The shape of the funnel' implicitly signals an aggregate/overview use case versus the per-lead tools (crm_list_leads, crm_get_lead), but the agent must infer that; no alternative is named.

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. The description adds genuinely new context beyond the structured fields: the crm:read scope requirement and the fact that the response carries the time the snapshot was built (a freshness signal).

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 tightly-packed sentence with no waste, and the scope tag is clearly delimited at the end. It is front-loaded but slightly over-compressed, requiring the reader to parse 'KPI contract as the dashboard renders it'.

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 elaboration, and there are no parameters to document. The description covers what the tool returns, its freshness timestamp, and its auth scope, which is sufficient for a no-arg read tool; only the sibling-selection question is left open.

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 per the rubric the baseline is 4. There is nothing for the description to compensate for, and it correctly avoids inventing parameter guidance for a parameterless 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?

States a specific resource — the workspace's own KPI contract as the dashboard renders it, plus the build timestamp. It is distinguishable from marketing_snapshot and partner_overview by the 'workspace's own' qualifier, though the verb is implicit and 'KPI contract as the dashboard renders it' is somewhat abstract phrasing.

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

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

There is no when-to-use guidance and no mention of alternatives, even though sibling tools like marketing_snapshot, partner_overview, and crm_pipeline_overview clearly overlap in the snapshot/KPI space. The agent must infer which snapshot to 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the [scope: marketing:read] auth requirement, which tells the agent a permission is needed before calling. It does not state the reporting period or freshness of the snapshot, but nothing contradicts the annotations.

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

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

A single front-loaded sentence lists the metric payload, followed by a bracketed scope tag. No filler, no restatement of the title, and the most important content (what you get) comes first.

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

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

With an output schema present, the description needn't explain return values, and with zero params the input side is trivially complete; the annotations cover safety. The only gap is the reporting window or aggregation scope of the snapshot, which an agent must infer.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies there is nothing to configure — it is a fixed snapshot — and the empty schema with additionalProperties:false is consistent with 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?

The description names the resource (advertising performance) and enumerates the specific metrics returned: spend, reach, clicks, cost per lead, per campaign, plus a CRM join. An agent knows exactly what this returns. It does not, however, distinguish itself from sibling dashboard_snapshot or partner_overview, which sound like competing overview tools.

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

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

Usage is only implied: 'advertising performance ... per campaign, plus the CRM join' suggests when the tool is relevant, but there is no when-to-use statement, no exclusion, and no reference to a sibling alternative such as ad_attribution or dashboard_snapshot. The scope tag gives a permission constraint rather than selection guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the auth/token binding requirement and the partner:read scope.

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 front-loaded sentence that leads with what the tool returns, then closes with the auth constraint. The middle is a dense comma-list of returned fields, which is efficient but slightly less scannable than shorter phrasing.

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 elaboration, and the description still supplies the one thing an agent cannot infer from structure: the partner-bound token requirement. Nothing needed to invoke this zero-param 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?

With zero parameters and 100% schema coverage, there is nothing for the description to disambiguate. The baseline for a parameterless tool applies, and no parameter meaning is misstated.

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 (this partner's own cabinet) and enumerates its contents: referral code/link, registered clients, agreed commission rate, accruals, and held grants. It is clearly distinguishable from siblings like whoami, crm_* and dashboard_snapshot, which cover different subjects.

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 hard precondition and a when-not: 'Only answers for a token bound to a partner,' plus the required scope [partner:read]. That is clear usage context, though it never names an alternative tool or when a caller should prefer a different overview.

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 value beyond the schema by disclosing that customer numbers are masked in the output and that the call requires the crm:read scope — both real behavioral facts an agent can't get from annotations alone. It stops short of describing pagination/truncation behavior at the 200-row cap.

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 fragments, front-loaded with the returned dimensions and no filler. It is efficient, though the terseness borders on under-specification since no sentence states the operation itself.

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 masking and scope notes cover the non-obvious behavior. What is still missing for reliable invocation is a clear statement of what the tool does (list recent calls?) and whether results are ordered or windowed by the since parameter.

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%: 'limit' documents the row cap and 'since' documents the accepted values (today | week | month | 7d | ISO timestamp in Asia/Dubai days). The description contributes nothing about either parameter, so the baseline of 3 for fully documented schemas 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 lists returned fields (direction, disposition, talk time) rather than stating the operation — there is no verb such as 'list' or 'retrieve', so an agent must infer that this returns voice call records. The noun 'calls' plus the field list gives a workable sense of the resource, but it never distinguishes itself from siblings like agent_conversations or crm_list_leads.

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

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

No when-to-use guidance at all: nothing says this is the right tool for pulling voice-call metrics versus agent_conversations or the crm_* tools. The only implicit signal is the crm:read scope tag, which hints at the domain but not the selection criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the non-obvious behavioral trait that this call gates the usefulness of the other tools, which the annotations cannot express. It does not discuss auth requirements or error behavior when a token is invalid, keeping it out of the top band.

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, zero filler, and the identity/scope payload is front-loaded ahead of the call-ordering advice. 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 the return shape is covered elsewhere; with no parameters and no nested objects, the only thing an agent needs is what it reveals and when to call it, both of which are stated.

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 the baseline is 4. There is nothing further the description could add about 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 precisely what is returned — token identity, readable workspace, and carried scopes — with a specific resource (the auth token) rather than a generic 'get info'. An agent can distinguish this diagnostic from every sibling tool (crm_*, marketing_*, agent_*) 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?

'Call this first' gives an explicit ordering instruction and a reason (it tells you which other tools will work), which is unusually actionable guidance. It stops short of naming specific alternatives or exclusions, but for a zero-parameter prerequisite tool that omission is minor.

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