sage_federation

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

With no annotations, the description carries the full burden and does so reasonably: it declares read-only and caller-filtered behavior, rules out mutations as operator-only, and explains the eligibility semantics of the two domain categories (shared_read_domains cleared live peer-policy and linked-reader gates; read_candidate_domains are policy intersections only and must be checked via read_authorization). It omits auth/permission prerequisites and any cost or latency characteristics.

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?

Front-loaded with the discovery purpose, then routing guidance, then domain-eligibility semantics, then the safety boundary. Six dense sentences with no filler, though the shared_read_domains/read_candidate_domains sentences are jargon-heavy and assume terms not defined elsewhere in the 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?

No output schema exists, so the description must convey what comes back; it does enumerate the returned categories (connected SAGEs, remote agents, copy offers, domain authorization) and clarifies the trust status of each domain class. It does not describe result shape, ordering, or that results are paged — the latter is only recoverable from the param description.

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 schema already explains peer_cursor as an opaque bounded-page continuation with an omit-for-first-page rule. The description never mentions the cursor or pagination, so it adds nothing beyond the schema; baseline 3 applies.

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 concrete verb (Discover) plus the concrete resources returned: connected SAGEs, remote agents, copy offers, and the caller's domain authorization. It explicitly separates itself from sage_find_agent for name-based recipient lookup, though it does not disambiguate against other discovery-ish siblings like sage_directory, sage_domains, or sage_status.

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?

Gives one explicit routing rule ('To find a recipient by name, use sage_find_agent for one lookup across local and connected SAGEs') and one explicit exclusion ('pairing, sharing, subscriptions, and other mutations remain operator-only'), which tells the agent what this tool cannot do. No statement of when federation discovery is the preferred next step versus sage_directory or sage_list.

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