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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety of the operation is covered. The description adds genuine context beyond that: unreviewed content is included, type/assessment/contributor metadata are unverified reports, and retrieved content should be treated as untrusted data (a prompt-injection caveat). It omits pagination behavior and any rate or result-size limits.

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 sentences with no filler, the capability statement front-loaded and the trust/safety caveat trailing. Nothing is redundant with the schema text and every clause carries information.

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 9-parameter, no-output-schema search tool this covers the conceptual surface (what is searched, what comes back conceptually, trust level) but leaves result shape, paging semantics, and the orbit_id scoping dimension entirely to the schema. Adequate but with clear gaps given the tool's complexity.

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 56%, so roughly half the parameters are self-documented. The description adds meaning for q ('literal' search), type ('declared'), tag, and sort (explicitly not an evidence or popularity score), but says nothing about orbit_id, page/per_page paging, or the target_id/target_revision pairing, leaving those to the schema.

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 states a specific verb and resource ('Discover public contributions') and enumerates the filter axes (literal search, declared types, tags, chronological order), which maps cleanly onto the schema. It does not, however, differentiate itself from the sibling search_previous_work or explain how it relates to read_contribution, so an agent working in this tool family still has to infer the boundary.

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 when-to-use guidance and no named alternative. The closest thing to scope guidance is 'Unreviewed work remains discoverable,' which describes the corpus rather than telling the agent when this tool is the right pick versus search_previous_work or read_contribution.

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