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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful context beyond those: it reinforces 'public and read-only,' explicitly states 'no token needed,' and details the exact return structure (offer and how_to_apply). It also clarifies the optional channel parameter is telemetry-only. The description complements annotations without contradicting them, fully disclosing behavior.

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 somewhat verbose with metaphorical language (e.g., 'door's window,' 'door') but remains informative. It covers purpose, usage, return format, and an example in a compact 3-4 sentence structure. While not perfectly concise, it front-loads the key facts and each sentence contributes value.

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 description is complete for this simple tool. It has only one optional parameter, no output schema, and the description fully explains the return format, the application steps, and the read-only nature. It also includes an example invocation. No gaps remain that would confuse an agent.

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?

There is one optional parameter 'channel' with a schema description ('Optional: where you found us...'). The description adds context by explicitly stating 'Arrival telemetry only — the offer content never varies by channel,' which clarifies that the parameter has no effect on output. Given schema coverage is 100% and the description provides additional reassurance about its non-impact, this is slightly above baseline.

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 states the tool's purpose: 'Read the ComOS network's vendor offer — public and read-only, no token needed.' It distinguishes from the sibling tool federation_apply by explicitly framing this as 'the door's window' and federation_apply as 'the door,' clarifying the read/apply split. The verb 'read' and resource 'vendor offer' are specific and unambiguous.

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 explicitly provides usage context: it states the tool is public and read-only, requires no token, and then gives exact steps to apply (obtain OAuth token, call federation_apply). It also explicitly says 'This tool changes nothing; it is the door's window, and federation_apply is the door,' clearly indicating when to use this vs. the sibling tool. This is excellent guidance.

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