sage_federation

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

With no annotations provided, the description carries the transparency burden. It clearly discloses read-only and caller-filtered behavior, distinguishes between vetted and candidate domains, and notes that mutations are operator-only. The parameter schema adds pagination behavior. It does not describe return format, but given the safety and scope disclosures, it is well above minimal viability.

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 three sentences long with every sentence adding crucial context: purpose, eligibility caveats, and safety constraints. It is front-loaded with the primary action and contains no filler or redundant wording.

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?

Given the tool's discovery role, it covers the essential aspects: what can be discovered, nuances of eligibility, caller filtering, and the operator-only boundary. The schema handles pagination. Without an output schema, a description of the return structure would be helpful, but the info provided is sufficient for an agent to use the tool safely and decide next steps.

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 only one optional parameter (peer_cursor) and the schema description is 100% detailed, explaining the opaque bounded-page continuation and the fact that MCP never auto-walks pages. The tool description does not add further parameter-level meaning, so the baseline of 3 applies since the schema already carries the semantics.

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 opens with a specific verb 'Discover' and enumerates clear resources: connected SAGEs, remote agents, copy offers, and caller domain authorization. This clearly distinguishes it from sibling tools focused on scope, governance, or messaging.

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 provides strong contextual guidance: it explains which domains are eligible for federated recall (shared_read_domains) and warns that read_candidate_domains require further authorization checks. It also states that operating on these resources requires operator-only actions, implicitly telling the agent not to attempt mutations here. It does not explicitly name alternative tools, but it clearly delineates when this discovery tool is appropriate.

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