Data Parrot AI Revenue Analyst for HubSpot

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint, so safety is established. The description adds behavioral context: the multi-step workflow (manifest first, then drill-down) and the explicit claim that it describes data rather than returning evidence. This goes beyond the annotations by explaining how the tool is meant to be used, which is valuable for an agent.

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

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

The description is three sentences with no redundancy. It front-loads the purpose, then gives a concise usage instruction, and ends with a clear limitation. Every sentence earns its place, and there is no filler.

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

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

Given the tool has 9 optional parameters and zero schema descriptions, the description is not sufficient to fully understand how to use all features. It covers the high-level flow but omits details on pagination, filtering options, and the distinction between the two page/option_page parameters. The output schema exists, so return structure is known, but the parameter semantics are incomplete, leaving the agent with significant ambiguity.

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

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

Schema description coverage is 0%, so the description must compensate for all 9 parameters. It only hints at 'section' and 'detail' by saying 'use an advertised section and detail,' but it does not explain the other parameters (page, page_size, search, field_id, lifecycle, option_page, option_page_size). The agent is left to guess their semantics. The description provides a general workflow but fails to clarify the full parameter landscape, making this a significant gap.

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

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

The description clearly states the tool's role: 'Discover what Data Parrot knows about this workspace and how to retrieve it.' It distinguishes itself from data-returning siblings by explicitly noting 'This tool describes data; it does not return business evidence.' The verb 'Discover' is specific and the resource is clear, though it could be more precise about what 'Data Parrot knows' entails.

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 pattern: 'Call with no arguments for the compact master manifest, then use an advertised section and detail for focused fields...' This tells the agent when to call with no args and how to proceed. It also gives an implicit exclusion: since it does not return business evidence, the agent should use sibling tools like get_deals when actual data is needed. No explicit alternatives are named, but the limitation serves as 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 read-only, idempotent, and non-destructive behavior. The description adds the non-obvious behavioral detail that query settings are preserved across the expansion, which helps set expectations about how the continuation works. It does not contradict any annotation.

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 the action and object front-loaded and the input contract in the second sentence. There is no repetition of schema fields or annotation properties, and every clause adds 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 simple two-parameter tool with annotations and an output schema, the description covers the essential contract: what to pass, what operation occurs, and that query settings are retained. Minor omissions like continuation-token expiry or invalid-ID handling exist, but the low complexity and presence of an output schema keep this from being a significant 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?

With 0% schema description coverage, the description carries the semantic burden. It defines result_id as identifying a prior Data Parrot result and continuation_id as one that was returned by that prior result, providing the key relational meaning missing from the schema. It does not detail ID formats or error behavior, but the core meaning of both parameters is conveyed.

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 ('load') and resource ('more data or supporting evidence from a prior Data Parrot result'), which clearly distinguishes this tool from the sibling data-getters and workspace-management tools. The reference to continuation_id makes the pagination/expansion purpose unmistakable.

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

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

The description gives clear invocation context: use it after you already have a result_id and a continuation_id returned from a prior result, and it explicitly preserves query settings. It does not contrast this with sibling tools, but the continuation_id prerequisite is an unambiguous trigger that makes the appropriate usage scenario evident.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: partial row disclosure, ranked-list semantics, and an explicit warning not to sum company financial values. 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?

The description is four sentences with no filler. It front-loads the primary purpose, then provides essential caveats and a sibling alternative. Every sentence earns its place.

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

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

The output schema and annotations reduce the burden on the description. The description covers core behavior, partial-data semantics, aggregation restrictions, and the key sibling alternative. Given the large number of parameters, it is not a complete manual, but it is sufficient for correct basic invocation and safe handling of 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 only 14% schema description coverage, the description carries a high burden for explaining parameters. It provides useful high-level semantics around rows vs. count groups, ranking, and financial values, but does not detail the 21 parameters. The self-explanatory parameter names and sparse schema descriptions partially compensate.

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

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

The description uses a specific verb and resource: 'Return exact Customer Health KPIs plus paginated company rows or count groups.' It clearly differentiates from siblings by explicitly routing open expansion opportunities to get_deals, making the tool's role in the catalog clear.

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 explicit routing guidance: 'Use get_deals for open expansion opportunities.' It also provides use-specific caveats like stating the ranking basis for ranked risk lists. It does not comprehensively contrast against every sibling tool, but it is strong for the main alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully cover the safety profile. The description adds no extra behavioral context beyond the action itself—no mention of what the output contains or any side effects. Since it's consistent with annotations and there's no contradiction, 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 sentence that is direct and front-loaded. Every word earns its place, and there is no redundancy 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?

Given an output schema exists and the tool takes no parameters, the description is sufficient for an agent to invoke it correctly. It could optionally mention that calling it does not alter workspace state, but the annotations already convey that. The tool is simple enough that nothing critical is missing.

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

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

The tool has zero parameters, so the schema is fully self-describing. The description adds no parameter details because there are none. Baseline 4 applies per the rubric for zero-parameter tools.

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 verb ('Report') and a specific resource ('this MCP connection's workspace-access state'). It distinguishes from sibling tools like switch_data_parrot_workspace or reset_data_parrot_workspace_binding, though it doesn't explicitly name them. The purpose is unambiguous but could be slightly more explicit about being a status-only check.

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 guidance is provided on when to use this tool versus the workspace-management siblings. It doesn't mention whether to call it before switching, after resetting, or in any specific workflow. An agent must infer usage from the sibling names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond this: Data Parrot AI analysis is included only for open deals, and the response includes seller-entered next steps and future scheduled activities. 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 sentences, front-loaded with the core action and then enriched with return contents and use cases. Every clause adds value, and there is no repetition of schema or annotation information.

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

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

With an output schema present, the description does not need to spell out return values. It covers the main use cases, a conditional behavioral detail, and gives a hint about the columns parameter. Slightly more explicit guidance on how columns map to the parameter 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 0%, so the description must compensate. It does add partial meaning: deal_id is 'one known deal ID' and columns are implied by 'selectable HubSpot fields.' However, it does not explain how columns should be provided, the meaning of null, or the default behavior, leaving an important gap for a schema with no property descriptions.

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

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

The description opens with a specific verb and resource: 'Return details for one known deal ID,' which clearly distinguishes this from the plural get_deals sibling. It also lists concrete content areas (fields, custom properties, associations, next step, activities, AI analysis), making the tool's purpose unambiguous.

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

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

The description provides clear usage context: use it for deal details, forecast confidence, or a deal's recorded won/lost reason. It does not explicitly name alternative tools or state when not to use them, but the 'one known deal ID' phrasing and use cases imply the boundary against get_deals and get_forecast.

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 mark this as readOnly, idempotent, and non-destructive, so safety is covered. The description adds the useful behavioral detail that open deals expose manual forecast_status and AI forecast_category, and that owner selection is exclusive. 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?

Three sentences, front-loaded with the high-level operation and no filler. Each sentence earns its place: scope, owner-selector rule, and catalog pointer.

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 35-parameter tool with 26% schema coverage, a three-sentence overview leaves out pagination, grouping specifics, date-range semantics, and most filter categories. The output schema helps, but the input schema's low coverage means the description needed to add more operational detail to be complete enough for safe invocation.

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

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

Schema description coverage is only 26%, so the description carries a large burden. It names broad capabilities (activity counting, grouping, ranking) and owner selector exclusivity, but it does not explain or enumerate the many undocumented parameters such as pipeline_stages, close_date_range, custom_property_filters, or pagination controls.

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

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

The description names a concrete verb set (search, filter, count activity, group, rank) plus the resource (CRM deals) and the statuses returned. It does not explicitly distinguish get_deals from its sibling get_deal, so it falls just short of a top score.

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 instructs the agent to choose one owner selector, and it routes broader AI analysis to deals/analysis_concepts in the catalog. It does not state exclusions for singular deal lookup or forecast tools, but the search/analysis framing supplies clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds useful context about ordering (reverse-chronological) and the types of events included, which goes beyond the annotations and provides behavioral insight without contradiction.

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

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

The description is a single, front-loaded sentence that states the verb, resource, and content scope with zero waste. It is efficient and immediately informative.

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 presence of an output schema (not shown but declared), the description need not explain return values. The tool is simple with one parameter, and the description covers purpose, scope, and ordering. Nothing essential for an agent 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 0%, so the description must compensate for the single parameter deal_id. It adds the semantic constraint that the deal must be 'known' (i.e., already exist), which is not in the schema and helps the agent understand it cannot be used to create a deal. This is valuable, though it doesn't elaborate on format or retrieval.

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 ('Inspect') and identifies the exact resource: a single deal's reverse-chronological timeline of Data Parrot AI assessments, CRM changes, and customer engagements. This clearly distinguishes it from siblings like get_deal (basic deal info) or get_engagements (only engagements) by naming the composite content.

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

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

The description implies use when you have a known deal_id and want its full timeline, but it does not explicitly mention alternatives or state when not to use it. The purpose is clear enough that an agent could infer context, but there is no explicit routing guidance among the many sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the date-bounded scoping and the distinction between activity types and object events, which is useful behavior context, though it leaves details like pagination and grouping to the 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?

Two sentences, no filler, with the core operation front-loaded and the conditional routing rule in the second sentence. Every word earns its place.

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

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

The tool is complex (29 params) and the description is minimal, but the schema carries detailed parameter semantics and an output schema exists, so return-value documentation isn't required. The description gives the essential orientation an agent needs before reading the schema, though a sentence about grouping/filtering would have made it more self-sufficient.

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

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

Only 41% of parameters have schema descriptions, so the top-level description needs to compensate, but it only gestures at engagement_type choices and 'association filters.' It does not explain the required date_range shape, the selector semantics of owner_ids/team_ids, or the grouping/pagination parameters, leaving a large gap.

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

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

States a specific verb ('Return') and resource ('date-bounded activities or deal/lead CRM object events'), and it distinguishes between activity records and dated object events. It does not name or contrast sibling tools explicitly, so it falls just short of full 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 description gives a clear context for the tool—retrieving date-bounded activities or object events—and provides an explicit routing rule: for deal/lead-associated activities, choose meetings/calls/emails/communications and pair them with association filters. It does not state exclusions or name alternative tools, but the primary use case 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 readOnlyHint, idempotentHint, and openWorldHint. Beyond that, the description adds concrete behavioral facts: closed deals are excluded, and it differentiates forecast_status (manual) from forecast_category (AI). This adds useful context without contradicting 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 three sentences with no waste. The core purpose is front-loaded, followed by the confusion-resolving Field terminology (forecast_status vs forecast_category) and the routing guidance. 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?

Given the output schema (not shown, so return values are documented elsewhere) and annotations that already cover safety, the description adequately covers the tool's purpose, scope, and relationship to siblings. It might mention pagination or result ordering, but those are typically covered by the output schema or defaults, so the description remains complete enough for correct agent selection and 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 50%, and the description does provide some parameter-level meaning (e.g., forecast_status is manual, the tool returns open-deal totals). However, it does not explain page, page_size, forecast_status values, pipeline_stages, or the exclusive selectors beyond their schema text. The added semantics are helpful but do not fully compensate for the half-undocumented 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 opens with a specific verb-resource statement: 'Return exact open-deal totals, configured manual forecast_status, and AI assessments.' It differentiates itself from siblings like get_deals by explicitly noting that closed deals are excluded and that forecast_status is manual while forecast_category is AI.

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 provides explicit routing: 'For target-attainment questions, consider won deals from the same scope and date range... get_deals returns those deal sets, get_win_loss explains outcomes, and get_deal provides one deal’s details.' This clearly tells the agent when to use alternatives, complemented by the observation that closed deals are excluded from this tool.

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

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

The description adds value beyond annotations by disclosing the behavior that unavailable history is treated as missing, not zero, and that comparisons require aligned ranges and order. Annotations already indicate read-only, idempotent, and non-destructive, but the description enriches the operational context without contradicting them.

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

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

Two sentences with zero filler. The purpose is front-loaded, and the comparison guidance is directly actionable. Every clause earns its place, making it highly concise and well-structured.

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

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

Given the tool's complexity (17 parameters, nested objects, output schema), the description is minimal. It covers key caveats like missing data and comparison alignment but omits pagination behavior and broader use-case guidance. The output schema likely covers return format, and the schema covers parameter specifics, so it is not severely lacking, but more context would improve completeness for an agent.

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 59%, so the schema handles many parameters well, including history_view, movement_direction, and columns with detailed descriptions. The description itself does not add parameter-specific semantics beyond referencing 'non-date arguments' and 'explicit ranges,' which are generic. Baseline 3 is appropriate given moderate schema coverage.

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

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

The description clearly states the tool returns pipeline history for a specific inclusive date range. The verb 'return' and resource 'pipeline history' are specific. However, it does not distinguish from sibling tools like get_deal_timeline or get_forecast, so it misses the top score for 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 description provides explicit guidance for comparisons (call once per range, identical non-date arguments, align by ranges, treat unavailable as missing). However, it does not state when to use this tool instead of alternatives like get_deal_timeline or get_forecast, nor does it give exclusions. The guidance is useful but incomplete for selecting between 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 and idempotentHint. The description adds valuable behavior: response format (speaker turns with timecodes) and pagination handling. These are beyond annotation scope and help the agent predict output and next steps.

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. The core purpose is stated first, followed by the response shape and pagination. Every sentence contributes essential information.

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

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

With an output schema present, the description covers key aspects: source of ID, response content, and pagination. It omits error scenarios, but for a read-only idempotent tool with annotations and schema, this is adequately 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 coverage is 100%, so parameters are documented. The description augments this by explaining when cursor should be used (when has_more is true) and clarifies that transcript_id comes from a prior get_engagements call, adding practical context not in the schema.

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

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

The description clearly states the tool reads a single transcript by transcript_id, sourced from get_engagements. This distinguishes it from siblings like get_deal or get_engagements, making the purpose 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?

Provides explicit context that transcript_id comes from get_engagements and gives a concrete instruction for pagination (call again with cursor when has_more is true). It does not explicitly contrast with alternatives, but the source linkage and pagination guidance are sufficient for typical usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the output composition — grouping by reasons/factors with attribution, ranking, and supporting-deal evidence — which orients the agent to the result shape. The word 'Return' is consistent with the read-only annotation; no contradiction exists.

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

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

The description is a single dense sentence with no wasted words. The primary action and output structure are front-loaded. It could arguably be split for readability, but it is appropriately sized 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?

The tool is complex (13 parameters, several exclusive selectors, multiple enum-driven options), yet the description is just one sentence. The output schema covers return values, but the description does not address usage context, selector exclusivity, or how this analysis differs from the adjacent get_deals tool. For a tool this complex, additional guidance would be warranted.

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 54%, which sits between the high and low thresholds, so the description carries a moderate burden. It indirectly maps to signal_rank_by (ranking), signal_attribution_mode (attribution), and include_supporting_deals (supporting-deal evidence), which adds some value. However, it doesn't clarify the required deal_statuses or the semantics of the exclusive selector filters (team_ids, owner_ids, owner_scope) that would matter for correct invocation.

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 ('Return'), a clear resource ('Data Parrot closed-deal analysis'), and enumerates the output groupings (win/loss reasons, sales performance factors, buyer decision factors) plus attribution, ranking, and evidence. This is a specific and informative purpose statement. However, it doesn't explicitly differentiate from siblings like get_deals, which could also surface closed-deal data, so it loses the full point.

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 no guidance on when to use this tool versus the 13 sibling tools, including close relatives like get_deals, get_forecast, and get_pipeline_history. No exclusions, prerequisites, or alternative tool references are provided. The agent must infer the analytical use-case context entirely on its own.

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 cover mutation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds the user-consent requirement as a behavioral precondition, which is meaningful context beyond the annotations, though it doesn't detail side effects of the reset.

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

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

A single sentence with zero waste. The precondition leads, followed by the action and outcome. Nothing is redundant or extraneous.

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 consent-gated reset action with an output schema and rich annotations, the description covers the essential information: the precondition, the action, and the outcome. It could clarify what makes a binding 'unavailable,' but the output schema and annotations carry the remaining burden.

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

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

With zero parameters, the description carries no parameter burden. The baseline for a 0-parameter tool is 4; the description correctly avoids inventing parameters and accurately implies a stateless action.

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 (reset), a specific resource (this MCP connection's unavailable workspace binding), and the resulting outcome (choose from active workspaces). It clearly distinguishes from siblings like switch_data_parrot_workspace and select_data_parrot_workspace, which operate on active workspaces rather than resetting an unavailable 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 front-loads the precondition 'After the user explicitly agrees,' giving a clear when-to-use condition. It implies this is for an unavailable/stale binding scenario, distinguishing it from the switch/select siblings, though it doesn't explicitly name alternative tools or state when NOT to use it.

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 already convey that the operation is a write (readOnlyHint=false), idempotent, and non-destructive. The description adds the user-selection constraint, which is valuable, but it does not disclose what happens on switch, whether it changes a binding, or what the output contains. This is adequate but not rich.

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

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

A single sentence that is front-loaded with the action and immediately communicates the critical safety constraint. No wasted words; every part earns its place.

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

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

For a one-parameter tool with annotations and an output schema, the description is mostly sufficient. The main gap is the missing relationship to select_data_parrot_workspace and reset_data_parrot_workspace_binding, and where workspace_options comes from. This could cause an agent to misuse the tool when several workspace-related siblings exist.

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 tenant_id parameter is already described as 'from workspace_options explicitly chosen by the user.' The tool description essentially restates this same constraint without adding new meaning about the parameter's format, source, or behavior.

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

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

The description states a specific action (switch) and resource (workspace), and includes a clear constraint (only to a user-selected workspace from workspace_options). However, it doesn't explicitly differentiate from the sibling select_data_parrot_workspace, leaving some ambiguity about how 'switch' differs from 'select'.

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 word 'only' gives a meaningful usage condition: this tool must be used exclusively with a workspace the user explicitly selected from workspace_options. It does not mention alternatives or explicit when-not-to-use scenarios, but the precondition is clearly stated and strong.

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