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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description doesn't repeat those. It adds useful behavioral context beyond annotations: default 'debt only' (interpretable as include_equity=false), pagination at 25 items, and the default quarter-end selection. It also notes figures are 'in the filer's own figures,' which is non-standard but valuable. No contradiction with annotations.

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 sentence that front-loads the core function ('Every position a BDC tagged at one quarter end') and packs the returned fields into a clear list. It is efficient with no filler or repetition of schema details (like types or defaults). The structure lets an agent quickly grasp the tool's output and key behaviors.

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?

Given 6 parameters with 50% schema description coverage and no output schema, the description provides a strong foundation: it lists all returned fields, mentions default quarter-end, pagination, and debt-only default. It does not explicitly describe sort options or the exact format of as_of (though schema covers that), and it omits any note about error handling or rate limits. Still, for a read-only portfolio tool, this is quite complete.

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 50% (dfx_id, as_of, cursor have descriptions; sort, limit, include_equity lack them). The description compensates for some gaps: it clarifies as_of's default, mentions pagination (implicitly covering limit and cursor semantics), and hints at include_equity via 'Debt only by default.' However, it does not explain the 'sort' parameter or its enum values, and the relationship between limit and pagination is only partially addressed. Overall, partial compensation but not complete.

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 states a specific verb ('get') and resource ('BDC portfolio'), then enumerates the exact fields returned (borrower, instrument, kind, lien, principal, fair value, etc.). It also clarifies scope ('one quarter end') and default behavior ('latest unless as_of is given'). This clearly distinguishes it from sibling tools like get_borrower_capital_structure or get_credit_facility.

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 guidance on when to use this tool versus alternatives. Among many sibling tools (get_borrower_facilities, get_credit_facility, etc.), the description does not provide a comparison or exclusions. The only contextual hint is 'Debt only by default,' which is a behavioral note, not a usage guide. An agent has to infer when this is the right tool.

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