build_context

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

With no annotations, the description carries the full burden. It does valuable work by disclosing the return payload (rendered context, provenance, omissions, reproducible optimization report) and a real caveat that token counts are estimates unless a server-side estimator is configured. It does not say whether stored records are modified, whether the call is side-effect free, or what happens when the budget cannot be met.

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?

Two sentences, front-loaded with the purpose and then the output contract. No filler, though the second sentence packs provenance, omissions, report, and the estimation caveat into one dense clause.

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 four-parameter, schema-rich tool with no output schema, the description does explain what comes back, which is the main gap it needed to fill. It is still incomplete on routing versus siblings and on failure behavior when the budget is exceeded.

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 all four parameters are already documented, and the baseline is 3. The description adds framing for tokenBudget ('under a token budget') and clarifies that records merge with stored records, but adds no syntax, defaults, or interaction detail beyond 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 uses a specific verb+resource ('Construct a compact, task-specific context') and states the mechanism ('combines stored records with any inline records'). It implicitly separates itself from ingest_records and search_context by being the composition/rendering step, though it never names those siblings directly.

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?

There is no explicit when-to-use guidance: nothing says to call build_context before search_context or instead of it, and no preconditions or exclusions are stated. The agent must infer from the name and from 'task-specific' that this is the final assembly step.

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