Company schema changes to describe behavior and fix some return types

[danielrenaud]

Problem

Some behavior was unclear, so I added notes to guide the implementation. Some return types seemed incorrect, so I changed them to something that makes more sense

Solution

Requested Reviewers

@kokoc @DrewML