datasets_pitchbook_funds_facets

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

With no annotations, the description carries the transparency burden. It discloses the return type ('terms aggregation counts') and the available facet fields, but doesn't mention how filters (q, run_id, etc.) affect aggregations, whether pagination exists, or that this is a read-only operation. This is minimal behavioral disclosure for a data aggregation tool.

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 precisely two sentences, front-loaded with the primary purpose and the facet enum list. There is no filler or redundant phrasing, making it highly efficient for its content.

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 7 parameters, 1 required, and no output schema. The description explains the core purpose but doesn't clarify how filter parameters interact with the aggregation, what the returned counts look like, or any additional constraints. Given the lack of annotation support, the description is too sparse for a complete understanding of invocation 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 description coverage is 100%, so the schema already documents all parameters. The description's facet enum list duplicates the schema's property description, adding no new meaning. The baseline of 3 applies since the description doesn't need to compensate for schema gaps.

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 function: 'Facet PitchBook funds dataset' and 'Returns terms aggregation counts'. It identifies the specific dataset (PitchBook funds) and the operation (facet aggregation). Although it doesn't explicitly contrast with sibling search/item tools, the name and wording unambiguously indicate a faceting endpoint.

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 explicit usage guidance is given. The description implies the tool is for obtaining facet counts but doesn't state when to prefer it over siblings like datasets_pitchbook_funds_search or datasets_pitchbook_funds_item. There's no mention of alternatives or exclusion scenarios, leaving the agent to infer usage from context.

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