company_brief

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does add value by declaring read-only behavior ('Read-only apart from nothing') and the return format ('JSON with rendered markdown'). However, 'sealed' is ambiguous (point-in-time snapshot? immutability?), and there is no disclosure about authentication needs, cost/complexity of generation, or behavior with partial inputs.

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 and appropriately short, front-loading the deliverable and its contents before the output format. The phrase 'Read-only apart from nothing' is awkward and slightly wasteful, but every other element — contents list, read-only note, output format — earns its place.

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?

The output schema exists, so return values need no explanation, and the contents list gives a solid conceptual overview. But this is a high-complexity tool — 7 parameters, 2 required, 0% schema coverage, no annotations, and an unexplained required bundle_json — and the description leaves critical operational gaps: how to construct the JSON inputs and when to select this over the many company_* siblings that cover its sections.

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 0%, so the description must compensate, but it never explicitly maps its conceptual sections to the seven parameters. The required parameters project_id and bundle_json are entirely unexplained — an agent cannot determine what bundle_json must contain. Some loose inference is possible (now → period, decisions_json → approvals, compliance_json → compliance, exceptions_json → exceptions), but that is guesswork rather than documentation.

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 names the deliverable (the operator brief) and enumerates its composite contents — period, due items, approvals with counterfactual briefs, cash, exceptions, compliance, retention, and explanations — which distinguishes it from granular siblings like company_revenue or company_approvals. However, the operative verb is only implied ('Read-only... JSON with rendered markdown') rather than explicitly stated as generate/retrieve/produce.

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 when-to-use or when-not-to-use guidance is given, and no alternative tools are named even though dozens of company_* siblings cover individual sections of this brief (company_revenue, company_approvals, company_exceptions, company_compliance). The 'operator brief' framing implies a consolidated-overview use case, but the agent must infer when this aggregate is preferred over calling the granular tools individually.

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