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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is covered. The description goes far beyond that by disclosing qualitative behaviors: 'commitment dollars repeat across reports' (data duplication), 're-ups are the plan's own words' (subjective labeling), 'estimates are labelled' (data quality), and 'nothing predictive is published' (no forward-looking statements). It also explains status semantics (COMMITTED vs DISCLOSED_HOLDING) and that 'a target is never an actual' – all non-obvious traits an agent must know.

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 long but information-dense, with no filler. It front-loads the row contents and filters, then appends caveats. While it is a single run-on block rather than bulleted, every clause adds value. The structure is moderately scannable for an agent, though it could be split into short sections for clarity. Given the amount of domain-specific detail, this is appropriately sized.

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 13-parameter search tool with no output schema, the description covers return contents comprehensively, all key filters, sort options, and critical data-quality caveats. It explains status semantics and the meaning of 're-up' and 'first-time'. Pagination (cursor, limit) is only in the schema, but that's acceptable since it's a mechanical detail. The description sufficiently equips an agent to select and call the tool correctly, including knowing what factors to be cautious about when interpreting 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?

Schema description coverage is 54%, so many parameters lack inline descriptions. The description compensates by enumerating all filter dimensions (allocator, manager, fund, consultant, status, bucket, re-ups only, first-time only, since date) and clarifies semantics that the schema leaves ambiguous, e.g., manager is 'who backs this manager', and statuses carry specific date meanings. It also explains the sort options. Though it doesn't mention every parameter (limit, cursor) explicitly, it gives enough context that an agent can map its listed filters to 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 opens with a precise enumeration of what each row contains ('allocator, fund as printed, manager and fund resolved to the pe / vc graphs...'), the statuses and their meanings, and the filterable dimensions. It clearly identifies the tool as returning raw commitment rows from plan disclosures, distinguishing it from aggregated commitment tools like get_commitments. The verb 'search' plus resource 'allocator commitments' is explicit and matches the name.

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 lists many filter options and explicitly states the data granularity ('One row per line of a plan's own disclosure'), but it never says 'use this when...' or names an alternative (e.g., get_commitments for aggregated totals). The sibling tool get_commitments likely provides aggregate commitments, but no explicit 'instead of' guidance is given. The caveats at the end ('A target is never an actual...') are more about data interpretation than usage conditions.

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