Get company information and settings

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses two things annotations cannot: that returned data egresses to the AI client and potentially its model provider, and that free-text fields (names, memos, descriptions, report cells) can carry private identifiers despite field projection and must be treated as untrusted input. That is substantive behavioral and safety context not derivable from structured fields.

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?

Content is front-loaded: purpose first, prerequisite second, safety disclosures last. The security clauses are dense and slightly boilerplate, but each adds information the agent needs to handle the output safely, so little is wasted.

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 single-parameter read tool with a full schema, complete annotations, and an output schema that documents return values, the description covers the remaining gaps a schema cannot: key provenance, read-only nature, data egress, and prompt-injection risk. Nothing an agent needs to call it correctly is missing.

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 coverage is already 100% for the single 'entity' parameter, so the schema carries the definition. The description adds operational meaning by tying the key to list_entities as its source and stressing that it must be explicit, which helps the agent avoid guessing a company name or ID.

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 names a specific verb and resource ("Read one company's CompanyInfo") and enumerates exactly what settings come back: report basis, fiscal-year start, book-close date, currency, multi-currency, class and department tracking, plus derived capabilities. That is enough for an agent to distinguish it from list_entities (which yields keys) and from list_reference_data or the report_* 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?

It gives the prerequisite workflow explicitly: an entity key must come from list_entities, which tells the agent which sibling to call first. It does not state when NOT to use it (for example, to prefer list_entities when the company key is unknown), so it falls short of explicit exclusions, but the usage context is unambiguous.

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