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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial beyond-schema behavior: plan-gated fields return null and appear in an item's `locked` list, `lockedCount` signals further results on higher plans, the agent must say data is plan-restricted rather than estimate, and the tool returns data only without rendering to the user. This is exactly the kind of operational context annotations cannot convey.

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 with purpose and scope, then workflow, then plan caveats. Every sentence carries information, but the paragraph is dense and the plan/locked discussion and the show-call instruction run together, making it slightly harder to scan than an ideally structured definition.

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?

With no output schema and a simple flat input, the description fills the remaining gaps: what the response contains (breadcrumb, Meta pages, grade mix, Momentum components), how locked fields behave, and the mandatory follow-up sightglass_show call with the resultId. An agent has everything needed to call and use the result correctly.

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 100%, so the parameter baseline is 3. The description still adds value by clarifying that `companyRef` is an id or slug sourced from search or an ad's advertiser, and by framing users' terminology ('brands' = companies). It does not add detail on projectId/workspaceId precedence beyond what the schema already says.

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 first sentence names the exact resource and scope: one company's full profile plus its six nearest competitors. It also explicitly separates itself from sightglass_search_companies (source of the id) and sightglass_get_company_activity (trend/launch history), so an agent can route without opening schemas.

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 states where the identifier comes from (search results or an ad's advertiser companySlug), names the alternative tool for activity data, and gives explicit operating conditions: works without a Replo account, and call sightglass_show afterwards. When-to-use, when-to-use-elsewhere, and prerequisites are all present.

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