Get Company Profile

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior, but the description adds critical behavioral nuance beyond that: total_awards/total_value/avg_value only count SAM Award Notices (10-30% of federal obligations), not total federal contract value. The warning that a contractor active only in FPDS will show total_value: 0 by design is exactly the kind of misleading-output disclosure an agent needs. This does not contradict any annotation.

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 but every sentence earns its place: main purpose, sibling differentiation, licensing context, parameter guidance, and a critical scope caveat. The use of a bullet for uei and an uppercase IMPORTANT note for the totals limitation makes key information scannable without bloating the text.

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 that an output schema exists, the description does not need to enumerate return fields. It covers the essential operational context: what data is included, what is excluded, how to obtain the parameter, and which sibling tools to use for other views. Combined with the annotations, this is fully complete for safe and correct invocation.

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 input schema provides only a bare string property name 'Uei' with no description, so the description carries the full burden. It compensates thoroughly by specifying the 12-character format and listing concrete source fields (search_companies, search_opportunities' award_uei_sam, or any tool returning a uei field). This is more than enough for an agent to correctly populate the sole parameter.

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 specific verb and resource: 'Get one company's aggregate profile', listing exact contents (SAM registration fields plus award-history totals). It explicitly distinguishes itself from get_company_awards and get_company_peers, so an agent can select it correctly among 60+ siblings.

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 states when to use this tool: for the SUMMARY view, with explicit routing to get_company_awards for a full paginated award list and to get_company_peers for similar firms. It also adds a licensing constraint ('Pro only') and explains where the required uei value can be obtained, leaving no ambiguity about appropriate invocation.

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