hcp_visit_frequency_by_segment

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

With no annotations provided, the description carries the behavioral disclosure burden. It does state the core behavior: quarterly frequency computed and grouped by region and specialty, and it hints at join compatibility through the segment_rollup reference. It does not disclose output shape, how optional filters affect results, or how quarters_back is applied, but the primary behavior is still clear.

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

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

The description is a single, front-loaded sentence with no filler. The first clause states the primary output and grouping, and the second clause provides a useful comparison target. 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?

The tool has no annotations, no output schema, four parameters, and sits among eight related HCP tools. The description provides one sibling comparison but omits important context such as default behavior when optional parameters are omitted, expected result structure, and how it differs from hcp_engagement_summary or hcp_list_interactions. More context is needed for an agent to reliably invoke and interpret 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?

The description adds meaning by indicating that region and specialty are grouping dimensions and that time is measured in quarters. However, it adds no additional semantics for quarters_back or interaction_type beyond what the schema already provides, and with 50% schema coverage the missing parameter explanations are only partially 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 description clearly states the tool produces quarterly interaction/visit frequency data broken out by region and specialty, so an agent can infer the resource and aggregation. It also references the sibling hcp_prescribing_trend_by_segment, adding context for comparison. It lacks a direct verb like 'returns' or 'aggregates', but the metric and segmentation are 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 gives a concrete intended use case: compare side by side with hcp_prescribing_trend_by_segment's segment_rollup for the same quarters. However, it does not explain when to prefer this over related siblings such as hcp_engagement_summary, hcp_list_interactions, or hcp_rep_activity, nor does it provide exclusions or alternative routing.

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