Get Shared Object

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description goes well beyond them: it discloses pollAfterSeconds refresh semantics, the HORIZON_API_KEY requirement, and detailed per-status failure behavior (409 no-auto-retry with newer revisions, 404 ambiguity, 422 data retention, 401 re-auth, 403 wrong-userId, 429 rate limit). The only reason it is not a 5 is that the error block is largely a status-code catalogue rather than tool-specific behavior, and the return shape is enumerated but not interpreted.

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?

Excellent front-loading with labeled sections (Use when / Not for / Requires / Side effects / Returns / Errors) so an agent can scan the decision-relevant parts first. It is verbose in the Errors block, where several status codes are enumerated and the 401-versus-horizon_test_connection cross-reference is a long detour, but almost every line carries operational 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?

There is no output schema, yet the description spells out the return shape ({object,pollAfterSeconds,serverTime}) and warns that dataBase64 is opaque and must not be interpreted. Combined with the full error taxonomy and auth requirements, an agent has everything needed to call this correctly and recover from failures.

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 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: sessionToken must be the accessToken produced by horizon_signin_email/horizon_signin_anonymous, and userId must be the identity that signed in (otherwise 403). It does not add anything about collection or objectId beyond what the schema already says.

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 and resource ('Reads one object') and immediately scopes it to 'under current permissions', which separates it from the plural listing tools like horizon_query_shared_objects and horizon_get_shared_collections in the sibling set. An agent can identify the single-object read without opening any schema.

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?

Provides an explicit 'Use when' clause (world-map/async-PvP access after reading horizon://docs/shared-objects) and an explicit 'Not for' clause naming four anti-patterns including background polling and page traversal, which is exactly the boundary against the query sibling. Prerequisites (sign in first, pass accessToken as sessionToken) are stated up front.

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