Communicate Developer Docs

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the description's 'read-only' restatement earns little. However, 'never accesses workspace or customer data' is a genuine data-boundary disclosure beyond the structured annotations and is valuable for an agent deciding whether the call is safe. It stops short of describing output size or rate 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?

Two compact sentences with the payload listed first and the safety note second; every clause carries information and nothing is padded.

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?

An output schema exists, so return-value detail is unnecessary, and the description summarizes the returned content well. For a zero-required-parameter, read-only tool the definition is nearly complete; only the overlap with the support-contact sibling is unaddressed.

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 description coverage is 100% and the single 'query' parameter is well documented in the schema itself, including that the full canonical summary is always returned. The description adds no parameter detail at all, so this is the baseline 3 with the schema doing all the work.

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?

States a specific verb ('Return') and enumerates the concrete payload: canonical API URLs, authentication boundary, and support contact. It is clear in isolation, but it does not differentiate itself from the sibling communicate_get_support_contact, even though it also returns support contact info.

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 second sentence describes the tool's safety posture ('public, read-only, never accesses workspace or customer data') rather than when to call it. There is no statement of when this is preferable to communicate_get_openapi_summary or communicate_get_support_contact, leaving selection to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds valuable context beyond the annotations by clarifying that no authenticated API call is made and that the authentication boundary is returned as part of the summary.

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 a single, well-structured sentence that front-loads the returned artifacts and ends with the no-auth constraint. Every phrase earns it place.

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?

This is a low-complexity documentation summary tool with a full output schema and safety annotations already in place. The description lists the returned artifacts and the key behavioral constraint, making it complete enough for an agent to invoke 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?

The single optional query parameter is fully described in the input schema, including the note that the complete summary is always returned. The description does not add syntax or semantics beyond what the schema already provides, so the baseline score for high schema coverage is appropriate.

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 uses a specific verb ("Return") and names the exact resources returned: canonical OpenAPI URL, API base URL, authentication boundary, and published REST operations. It clearly distinguishes the tool's content from sibling documentation tools, but it does not explicitly reference alternatives like communicate_get_developer_guide or communicate_get_support_contact.

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?

There is no explicit when-to-use or when-not-to-use guidance. The phrase "without calling the authenticated API" implies this is useful for unauthenticated documentation lookups, but the description does not state when an agent should choose this over the sibling documentation tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it reiterates the no-side-effect nature ('without sending a message') and pre-enumerates what is returned, so the agent knows this is a static informational lookup. Return format specifics are left to the output schema.

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?

A single front-loaded sentence that states the action, the returned content, and the no-side-effect guarantee with no filler. Every phrase earns its place.

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 zero-required-parameter read-only lookup with a full output schema and complete schema coverage, the description supplies everything needed: what is returned, that the operation is side-effect free, and that it is informational. Nothing required to invoke 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 description coverage is 100% and there is only one optional parameter whose behavior (keyword focus, full summary always returned) is fully documented in the schema. The description says nothing about the query parameter, so it adds no value here — baseline 3 is appropriate.

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 gives a specific verb ('Return') and an explicit resource list (support email, contact page, support policy, inquiry categories), which is clearly distinct from the sibling documentation tools. It does not name the siblings to route between them, but the resource domain alone makes the distinction obvious.

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 clause 'without sending a message' implies this is the read-only lookup path as opposed to actually contacting support, which gives implied usage context. However, there is no explicit statement of when to prefer this over the sibling tools or any preconditions.

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