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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful return-value context by listing fields like 'add-on counts (total and last 24 months)' and clarifies the output is dfx:pe: company ids, but it does not disclose pagination, sort behavior, or any edge cases beyond what is already in 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?

The description is dense but efficient, packing the definition, returned fields, filters, and the downstream cross-reference into a compact structure. The key concept 'platform companies as a sponsor's platform investment, or a company that has made add-ons' is front-loaded before the detail list.

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 no output schema, the description carries the burden of explaining return values, and it does cover most of what an agent needs: the result fields and the filterable attributes. It is missing clarity on what the sort modes ('add_ons', 'recent', 'activity') mean, which is relevant for selecting the right call 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 57%, so the description must add meaning for parameters lacking schema descriptions. It does map filters to concepts like 'name' for query, 'industry text' for sector, 'minimum add-ons in 24 months' for min_add_ons_24m, and 'owner firm' for owner_dfx_id. However, it does not explain the semantics of the sort enum values or limit beyond what the schema's enum/default already provide.

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 defines the resource: private equity 'platform' companies, including what qualifies as a platform and the key data returned (add-on counts, owners, scores). It also distinguishes the tool from the sibling find_pe_addons_for_platform by stating it returns dfx:pe: company ids for that downstream workflow.

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 usage by enumerating filters: 'Filter by name, state, industry text, minimum add-ons in 24 months or owner firm.' It also hints at a workflow by saying returns IDs 'for find_pe_addons_for_platform.' However, it does not explicitly state when to prefer this tool over alternatives such as search_private_companies or search_pe_transactions.

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