Data Parrot AI Revenue Analyst for HubSpot

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety needs no restating. The description adds real behavioral context beyond that: the progressive-disclosure pattern (empty call yields a manifest that advertises valid sections/details) and the requirement that search be paired with section+detail. It doesn't cover pagination or option-paging behavior, which the other params imply.

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 sentences, front-loaded with purpose, then workflow, then scope boundary; nothing is padding. The opening clause ('Discover ... when these are unknown') is slightly tangled but costs little.

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 detail is rightly omitted, and the manifest-then-section workflow is well conveyed. However, with 9 parameters at 11% schema coverage, the description leaves most callable knobs (lifecycle, field_id, the two paging pairs) unexplained, which is the main missing piece for correct invocation.

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

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

Schema description coverage is only 11% and only the 'search' param is documented there, so the description is the main hope for the remaining eight. It clarifies section/detail as manifest-advertised keys, but leaves lifecycle, field_id, page, page_size, option_page, and option_page_size completely opaque in both schema and description — a significant gap for a 9-param tool.

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

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

The description uses a specific verb ('Discover') and resource (supported fields, AI assessment meanings, filters, allowed values, workspace-defined properties) and adds an explicit negative scope: 'it does not return business evidence,' which separates it from the get_* siblings. It is slightly list-like rather than a single crisp statement, but an agent can tell it is a metadata/catalog inspector, not a data fetcher.

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 ('when these are unknown') and a step-by-step call sequence: no arguments for the compact manifest, then request an advertised section and detail, with the constraint that search requires both section and detail. It does not name any sibling alternative (e.g. calling get_deals directly instead of exploring), so the when-not 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, idempotentHint, destructiveHint=false, so safety is covered; the description adds real value by saying the original query settings are preserved and that the continuation_id must be one the prior result returned. It stops short of describing what happens with an expired or invalid continuation_id, which is the one behavior an agent could trip over.

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 action, then the required inputs, then the usage decision and the sibling exclusion. No filler and nothing repeated from the schema.

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

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

An output schema exists so return values need not be described, and the annotations cover the safety profile; the description supplies the continuation precondition and the get_transcript alternative. The remaining gap is failure handling for stale or mismatched continuation_id, which would matter for an agent recovering from an error.

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

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

Schema coverage is 0%, so the description must carry the load, and it does: result_id is tied to a previous result and continuation_id is constrained to 'one returned' by that result. It does not add format or validity details (string shape, expiry), leaving a small gap, but the meaning of both parameters is clear.

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 (retrieve) and resource (the next page / additional detail / supporting evidence of a prior Data Parrot result), plus the exact inputs that identify it. It also explicitly names the sibling that handles a different pagination case (get_transcript), so an agent can route correctly without opening either schema.

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

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

Gives an explicit trigger ('when the previous result offers a continuation needed to answer the question') and an explicit exclusion ('Transcript pagination uses get_transcript instead'). The precondition that a continuation must already have been returned is stated, which is the key routing fact.

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, so the description is free to add the non-obvious semantics: 'Do not sum company financial values' warns that cross-page aggregation is invalid, and 'describe partial rows as the highest-ranked returned accounts' discloses that a paginated slice is top-N, not a complete risk set. Those are real behavioral traits an agent would otherwise get wrong; return format and pagination mechanics are left to the output schema.

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

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

Four tight sentences: output modes first, then ranking/pagination caveat, then a costly-mistake warning, then the sibling route. Only the opening clause is soft marketing framing that could be replaced by a direct verb.

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 described, and the description does cover mode selection and two correctness traps. Given 21 optional parameters with near-zero schema descriptions, however, an agent still has to guess how to shape a real query, which is the dominant gap for a tool of this complexity.

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

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

With 21 parameters and only 14% schema description coverage, the description must carry the load and it explains almost nothing — no mention of columns, group_by/group_sort_by interplay, health_label, date ranges, has_open_deals, or detail mode. The only hints ('count groups', 'Do not sum financial values') are echoes of schema text, leaving most parameter meanings undocumented anywhere.

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 (companies / Customer Health) and the three output modes it can produce: exact Customer Health KPIs, paginated company records, and count groups. The opening sentence ('Identify customers needing attention, quiet accounts...') is more use-case framing than a verb, but the second sentence pins down what is actually returned, and it explicitly distinguishes itself from get_deals.

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 usage context (risk/health review, quiet accounts, health changes) and names one explicit alternative: 'Use get_deals for open expansion opportunities.' It stops short of stating when *not* to call it or covering the other siblings, but the routing hint plus stated scenarios give an agent enough to choose correctly.

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 as a read-only, idempotent, non-destructive operation. The description adds useful context by explaining that it reports workspace-access state, setup or permission requirements, and available workspace choices, which helps the agent understand the return content beyond the safety profile.

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 tightly written sentences with no wasted text. The primary purpose is front-loaded, and the second sentence adds a direct usage cue for the returned workspace options.

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 no parameters, rich annotations covering safety and idempotency, and an output schema. The description covers what the tool checks and how the returned workspace choices are intended to be used, which is sufficient for an agent to call it correctly.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to clarify. With no parameters, the baseline score is 4.

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

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

The description states a specific verb and resource: check this connection's workspace-access state, setup/permission requirements, and available workspace choices. It also implicitly distinguishes the tool from siblings by noting that returned workspace options are used when the user wants to select or switch workspaces.

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

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

The description gives clear context for use: call it to inspect access state and available workspace choices, then use the returned options when the user wants to select or switch workspaces. It does not explicitly name the sibling select/switch/reset tools or state exclusions, so it falls 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that: the AI assessment only applies to open deals, closed deals instead return the recorded won/lost reason, and the response carries seller-entered next steps and future scheduled activities. It doesn't describe paging or result-size behavior, which keeps it off 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 use case is front-loaded in the first clause, and each subsequent sentence adds a distinct fact (payload contents, how to use the reasoning, the timeline alternative, the closed-deal case). The return-value enumeration is dense but not padded; nothing is repeated.

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 only two parameters, full annotation coverage, and an output schema handling return structure, the remaining gap an agent could face is routing and output interpretation. The description covers both, including the open-vs-closed deal behavioral split.

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

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

Schema coverage is 0%, so the burden is on the description. 'One known deal ID' confirms the identifier is a single known deal, and 'selectable HubSpot CRM fields' hints at the columns parameter being a field selector. But neither the expected string format for columns nor any example field names appear, leaving the actual call syntax under-specified.

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 plus a use case: 'Prepare a deal review or pre-call brief for one known deal ID,' then enumerates the specific payload (CRM fields, custom properties, associations, next step, scheduled activities, AI assessment). It explicitly distinguishes itself from get_deal_timeline, so an agent can route between the two 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?

Names the scenario (deal review, pre-call brief) and the constraint (one known deal ID), and explicitly routes chronology requests to get_deal_timeline. It also carves out the closed-deal case. It stops short of saying when to prefer the sibling get_deals list tool or noting prerequisites, so it's strong 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 readOnly, idempotent, non-destructive, so safety is covered. The description adds useful context beyond them: it names the data sources blended into results (CRM fields, Data Parrot AI assessments, recorded activity counts), notes that open deals carry forecast_category, and states the default when owner selectors are omitted. It says nothing about result limits, pagination caps, or cost/latency of the heavy activity-count filters.

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 dense sentences, front-loaded with the highest-value scenario framing before mechanics, and the sibling pointer comes late where it belongs. No filler, though some sentences pack many clauses ("Search, filter, count activity, group, rank, and return...") at the cost of readability.

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 shape need not be described, and the read-only annotations cover safety. But for a 34-parameter tool with zero required params and many unlabeled AI-assessment enumerations, the description leaves the agent dependent on an extra catalog call (deals/analysis_concepts) and does not clarify interaction rules among exclusive selectors (owner_scope/owner_ids/team_ids) or group_by vs. group_sort_by for row results.

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 34 parameters and only 26% schema description coverage, the description carries a large compensation burden and only partly meets it: it explains the owner-selector defaulting, open-deal forecast_category availability, and the activity-count concept generally. Many high-impact filters (pipeline_stages, purchase_intent, sales_performance, overall_deal_health, competitive_position, deal_progress_status, close_date_confidence, custom_properties) are given no meaning at all and are deferred to a catalog lookup, leaving the agent unable to construct them from the description alone.

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 specific verbs and resource ("Find deals that need review", "Search, filter, count activity, group, rank, and return open, won, or lost deals") and enumerates concrete review scenarios (questionable Commit deals, forecast risk, stalled/dormant, outreach with no response). It explicitly separates itself from the sibling get_deal by scoping this tool to search and get_deal to a shortlisted deal's reasoning.

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 clear when-to-use framing (review triage, leadership involvement, forecast risk) and an explicit alternative: "Use get_deal for a shortlisted deal's reasoning and evidence." Also routes to the catalog when filter selection is unclear. It lacks an explicit when-not-to-use statement (e.g. bulk export vs. single-deal lookup beyond the get_deal pointer), which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing the reverse-chronological ordering and the three content categories the timeline merges. It says nothing about volume, pagination, or result limits, which matters for a timeline that can span an entire deal lifecycle.

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

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

Three sentences, each doing distinct work: purpose, returned content, and use cases. It is front-loaded with the core intent and free of filler, though the first two sentences overlap slightly around 'what changed' and 'CRM changes'.

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 rich annotations, an output schema covering return values, and only one parameter, the description does most of the necessary work: it establishes scope, content, ordering, and when to reach for it. The remaining gap is identifier expectations and result size for an open-ended historical range.

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

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

Schema description coverage is 0% for the single deal_id parameter, so the description carries the burden. It partly compensates by saying 'one known deal', implying the identifier must reference an existing deal and that only one deal is returned, but it never states the expected type (positive integer) or what happens with an unknown id.

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

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

The description gives a specific verb ('Explain', 'Return') and a precise resource ('reverse-chronological timeline of CRM changes, Data Parrot AI assessments, and recorded customer engagements') scoped to 'one known deal'. It implicitly distinguishes itself from snapshot-oriented siblings like get_deal and get_engagements through its 'what changed over time' framing, but never names an alternative, so it falls 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?

The final sentence gives explicit use cases: deal history, changes in risk or confidence, and the sequence of buyer and seller activity. That's clear positive guidance, but there are no exclusions or pointers to the competing siblings (get_deal, get_pipeline_history, get_engagements) that an agent might otherwise choose.

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, so safety is covered. The description adds a genuinely non-obvious semantic caveat: meeting subtype counts are lifecycle events, so the same meeting appears in both booked and held and must not be summed as distinct meetings. That is exactly the kind of counting pitfall that prevents wrong answers.

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

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

Front-loaded with purpose, then requirements, then routing, then the counting caveat, then the transcript handoff — a sensible priority order with little filler. The meeting-count sentence is long but earns its space because it prevents a real aggregation error.

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 29-parameter aggregation tool with an output schema and rich annotations, the description covers purpose, required inputs, type routing, association filtering, and the key counting pitfall. Pagination/grouping mechanics are left to the schema, which is acceptable given group_by and page_size are documented there.

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

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

With only 41% schema description coverage across 29 parameters, the description must compensate; it does explain engagement_type families and the association filters (deal_ids/company_ids/contact_ids) conceptually, plus the transcript ID pointer. But it is silent on many undocumented parameters (detail, remove_duplicates, show_unassociated, pipeline_stages, group_page_size), leaving half the surface to be inferred from names.

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 ('Inspect') with the resource set (emails, meetings, calls, communications, plus deal/lead events) and the analytical intent (buyer responses, rep activity). It also distinguishes the engagement_type families, so an agent can tell which records come back. It stops short of naming sibling analytics tools like get_deal_timeline or get_forecast as alternatives.

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

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

Explicitly states prerequisites ('requires an activity type and date range'), gives a routing rule for the confusing case ('use meetings, calls, emails, or communications for associated activities' rather than deal/lead types), and points to get_transcript for transcripts. No guidance on when to prefer this over get_deal or get_deal_timeline, which is the remaining gap.

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, so the safety profile is covered by structured data. The description adds genuinely non-obvious behavior: won actuals follow pipeline, owner, and close-date scope while open-stage filters apply only to open pipeline — an asymmetry an agent could not guess. It stops short of describing result shape or pagination, though an output schema exists to carry 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?

Four sentences, roughly 50 words, front-loaded with purpose before usage, alternative, and scoping caveat — a sensible ordering. The final sentence is dense and slightly cryptic out of context, but every clause carries real information, so nothing is 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 six-parameter nested tool with an output schema, the description covers purpose, routing, and the main scoping trap. Remaining gaps — the undocumented pipeline_stages shape and return-value expectations — are partly carried by the output schema, so the definition is adequate 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 67% and the schema already documents the exclusive owner selectors; the description adds meaning where the schema is silent, notably how pipeline_stages filters only bite on open pipeline and how owner scope interacts with won actuals. It reinforces group_by granularity (week/month/quarter) without restating the enum.

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 — answer sales forecast questions — and names the three inputs that make up the answer (forecast summaries, open pipeline, won actuals). It also distinguishes itself from get_deals in the same breath, so an agent can route between them without opening either schema.

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

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

Gives concrete use cases (forecast reviews, team or rep comparisons) and names the explicit alternative, get_deals, for individual deal detail behind the totals. The condition that selects the sibling is clear rather than 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, closed-world, so the safety profile is covered. The description adds non-obvious behavior: calendar grouping can pull in earlier dates, evidence dates live in scope.date_basis.range, and unavailable history must be treated as missing rather than zero. It stops short of covering pagination or result-size behavior across the two page-size params.

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 most important information (what it answers, which view to pick) is front-loaded, and the dense sentences each carry guidance. The final comparison sentence is somewhat compressed into a multi-clause run, but no sentence is filler.

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

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

An output schema exists, so return shapes need not be explained, and the primary analytical workflow is well covered. But for a 17-parameter tool, roughly eight parameters remain undocumented anywhere, leaving an agent to guess at stage filters, segmentation values, and paging behavior.

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

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

At 59% schema coverage the description usefully clarifies group_by (day vs calendar-boundary grouping), date_range bounds, and comparison alignment. However several parameters — start_stages, end_stages, segment_value, pipeline_stages, page, page_size, group_page_size — carry no explanation in either the schema or the description, so the coverage gap is not compensated.

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

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

The opening states a specific verb and resource — return pipeline history for a date range — and immediately enumerates the three supported analytical views (waterfall, stage-transition, deal-change). It also implicitly separates itself from state-only siblings by noting that snapshot 'shows state, not change drivers.'

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?

Explicit routing is given: start with waterfall for what changed, stage_transitions for stage-flow causes, deal_changes for supporting deals, and day grouping for exact date ranges. It also prescribes the comparison workflow (call once per range with identical non-date arguments, align by explicit ranges and returned order).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations by specifying speaker-turn timecodes and cursor-based continuation when data.scope.has_more is true.

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

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

Three sentences, front-loaded with the core purpose, then prerequisites, then pagination guidance. Every sentence contributes useful operational information without repetition.

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

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

The tool is a read-only transcript retrieval operation with full schema coverage, annotations covering safety, and an output schema. The description supplies the key remaining context: source of transcript_id, returned content shape, and pagination behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning by tying transcript_id to get_engagements and by explaining that cursor should be used with data.scope.next_cursor when more data exists.

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: reading the recorded conversation behind a meeting or call. It also names the substantive content returned (buyer statements, objections, decisions, next steps), making the tool clearly distinguishable from siblings like get_engagements.

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 prerequisite: the transcript_id must come from get_engagements, and it explains the pagination condition using data.scope.has_more and data.scope.next_cursor. It does not explicitly name when not to use the tool or alternative tools, but the usage context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is interpretive context — and it delivers: it warns to preserve unknown reasons and to distinguish attributed explanations from proven causes, which materially affects how an agent reports results. It stops short of describing pagination behavior for the capped group_page_size or how partial/empty analyses behave.

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

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

Four sentences, front-loaded with purpose then output shape then usage then a caveat; each sentence carries content. The final caveat sentence is slightly disjointed but earns its place as interpretation guidance.

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 and full annotations mean the description needn't explain return values or safety, and the conceptual framing of the three analysis groupings is useful. But for a 13-parameter tool, the unexplained required deal_statuses and the silent pagination/grouping limits leave an agent guessing about the most load-bearing inputs.

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 54% schema description coverage the description should compensate, and it does only conceptually via 'attribution, ranking, and supporting-deal evidence,' mapping loosely to signal_attribution_mode, signal_rank_by, and include_supporting_deals — all of which already have schema descriptions. The required deal_statuses, plus page, page_size, group_page_size, pipeline_ids, and custom_properties, get no explanation anywhere.

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 — explain why deals were won or lost and return a prepared closed-deal analysis — and enumerates the output groupings (win/loss reasons, sales performance factors, buyer decision factors). It is clearly distinguishable from raw-data siblings like get_deal and get_deals, though it never names an alternative explicitly.

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

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

'Use it to identify reasons associated with the most deals or revenue' gives a usage context, but it largely restates the tool's own purpose rather than discriminating between this and get_deals/get_deal_timeline/get_forecast. No when-not-to-use conditions or prerequisites (e.g. workspace binding, data availability) are given.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds real value on top: a consent gate (explicit user agreement) and the post-condition (the binding is cleared so the user can choose an active workspace). It doesn't say what happens if no unavailable binding exists or whether the reset is immediate.

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 sentence, no waste, and the gating condition (user agreement) is front-loaded ahead of the effect.

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 rich annotation set, an output schema, and no parameters, the description covers consent and effect adequately. Only edge-case behavior (no unavailable binding present) is left unstated.

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

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

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly frames the call as taking no arguments.

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 (reset) and a specific resource (this MCP connection's unavailable workspace binding), plus the motivation (so the user can pick from active workspaces). This implicitly separates it from switch/select_data_parrot_workspace, though it never names those siblings outright.

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

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

Gives an explicit precondition — only after the user explicitly agrees — and implies the trigger condition is a binding that is unavailable. It stops short of naming switch_data_parrot_workspace or select_data_parrot_workspace as the alternatives for the other cases.

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

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds the important behavioral constraint that the agent must require explicit user choice, which is not captured in the annotations. It does not describe what happens to an existing binding, but the idempotentHint mitigates that concern.

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 short sentences with no filler. The main action and precondition are front-loaded, and the critical user-consent rule is stated clearly and separately.

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

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

For a single-parameter tool with annotations and an output schema, the description covers the essential precondition and user-consent requirement. It could be more complete by addressing how this differs from switching or resetting a workspace binding, but it is not materially incomplete 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?

The schema already provides 100% coverage, stating the tenant_id must come from workspace_options and be explicitly chosen by the user. The description reinforces this rule but adds little new parameter-level meaning beyond what the schema already conveys.

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

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

The description uses a specific verb 'Bind' and identifies the resource ('this MCP connection to one Data Parrot workspace'), making the tool's core action clear. It also mentions the prerequisite flow via get_data_parrot_access_status, which adds context, but it does not explicitly contrast itself with sibling tools like switch_data_parrot_workspace or reset_data_parrot_workspace_binding.

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

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

The description provides clear context for when to use the tool: after the user explicitly chooses from workspace_options returned by get_data_parrot_access_status. It also gives a strong exclusion ('Never choose a workspace for the user'), but it does not explicitly mention alternatives such as switch_data_parrot_workspace or state when not to use this tool.

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

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

Annotations flag destructiveHint=true and idempotentHint=true, which is surprising for a "switch" operation, yet the description never explains what is destroyed or replaced (current binding, cached catalog state, prior results). It adds only a provenance constraint, leaving the destructive semantics entirely unexplained.

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, front-loaded with the verb and the key constraint. No padding, though the terseness contributes to the gaps in the other dimensions.

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 covers return values, so that need not be described. But a destructive, binding-changing tool in a cluster of three workspace-management siblings needs at least a note on what switching displaces and how it differs from select/reset; that 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 single tenant_id parameter is already documented as coming from workspace_options with explicit user choice. The description restates that same constraint without adding format, validation, or error-behavior detail.

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

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

The verb and resource are clear ("switch ... workspace"), but the description never distinguishes this from the two other workspace-related siblings, select_data_parrot_workspace and reset_data_parrot_workspace_binding. An agent must guess whether switching is a re-selection, a reset, or a distinct 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?

"Switch only to a workspace the user selected from workspace_options" implies a precondition (user-chosen workspace) and an implicit prohibition on arbitrary tenant IDs. However, it gives no guidance on when to prefer this over select_data_parrot_workspace or when reset_data_parrot_workspace_binding is the right call instead.

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