portfolio

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

Annotations already mark this as readOnly, but the description adds substantial behavioral context beyond that: summary-endpoint failure still returns holdings with `totalsUnavailable`, lots are reported only when a wire key names them, derived figures are arithmetic rather than reads, and the entire endpoint is flagged as "PENDING VERIFICATION: this endpoint has not been observed live." It also discloses that paper mode reads a local ledger instead of the brokerage, which is exactly the kind of behavioral nuance an agent needs.

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?

Although the description is long, every sentence adds distinct value: scope, watchlist contrast, usage guidance, totals behavior, lot conversion, auth requirement, paper-mode caveat, and verification status. It is front-loaded with the core definition and structured with labeled paragraphs that make scanning easy. No filler sentences are present.

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 tool with no input schema and no output schema, the description is remarkably complete. It covers what data is returned, the distinction from watchlist, failure modes, units (lots vs shares), authentication requirements, paper-mode behavior, and the verification status of the endpoint. An agent can call this tool and correctly interpret its results without needing additional context.

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?

The tool has zero parameters, so the schema is empty and schema_description_coverage is trivially 100%. With no parameters to document, the description carries no parameter-semantics burden. The baseline 4 applies because there is nothing the description needs to add.

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 definition: "The user's ACTUAL stock holdings at Stockbit Sekuritas — what they own right now, at what average price, and what it is worth." It explicitly distinguishes this from a watchlist, naming the sibling tool and clarifying that this tool represents actual money at risk. The purpose is unambiguous and immediately differentiates it from related tools.

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 gives explicit when-to-use guidance: "Read it before offering any opinion that touches position sizing, concentration or whether to add." It also clarifies when not to use it versus watchlist with a concrete example about BBRI concentration. Paper-mode usage and the trading-session requirement are spelled out, leaving no ambiguity about when this tool should be invoked.

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