hcp_prescribing_trends

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

With no annotations, the description carries the full burden, and it does disclose the main behavior: it returns monthly trend data for new Rx, total Rx, and market share, and can be scoped to a product. It stops short of describing return shape, pagination, sorting, time-period semantics, or any side effects, but for a read-only reporting tool this is a reasonable but not exhaustive disclosure.

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

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

The entire description is one efficient, front-loaded sentence that starts with the core function and metrics, then adds scoping behavior and the required prerequisite. There is no filler, redundancy, or structural waste.

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

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

For a simple read-only tool with three parameters and no output schema, the description is close to complete: it states the returned metrics, the optional product scope, and the NPI requirement, which is enough for an agent to select and invoke it correctly. Minor gaps remain, such as clarifying whether the trend is a per-month series or how market share is computed, but these do not block correct use.

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% because months_back has no description in the schema. The description adds some meaning by tying brand_name to 'optionally scoped to one product' and indicating the output is monthly, but it adds no meaningful detail about months_back beyond what the schema's min/max/default already convey.

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: it states this tool provides a monthly prescribing trend for an HCP, naming the returned metrics (new Rx, total Rx, market share %) and optional product scoping. It clearly describes what the tool does, though it does not explicitly contrast it with the sibling hcp_prescribing_trend_by_segment, relying on the sibling name and the phrase 'for an HCP' to imply the difference.

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

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

Usage is implied rather than explicit: the description signals that this is appropriate when you need an HCP-level prescribing trend and states the NPI prerequisite and optional product filtering. However, it provides no when-not-to-use guidance or explicit alternatives, such as directing segment-level requests to hcp_prescribing_trend_by_segment.

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