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

With readOnlyHint=false, the description earns that annotation by disclosing the exact side effect ('Records a hash-only public USE record per mod') and the per-(agent, mod, task) idempotency of that record. It further details auth (X-Agent-Id/X-Signature/X-Timestamp, owner session token), and transport-specific signing rules including single-use signatures on the SSE bridge — behavior no annotation conveys.

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?

Purpose is front-loaded in the first clause, with auth and transport details following in labeled sections — effectively structured. The transport paragraph is dense and longer than the core purpose, but the signing details are operationally load-bearing rather than filler.

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 read-with-side-effect tool with three optional params and no output schema, the description covers purpose, side effects, auth, and transport quirks. The only modest gap is that it does not characterize the returned payload shape beyond 'FULL payloads' or mention the scoped_to tagging defined in the schema.

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%, so the three parameters (task_id, agent_id, project_id) are already documented in the schema, including the '*' project semantics and scoped_to tagging. The description adds only the task-level auto-injection framing, so the 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 precise verb+resource ('Get the mods ... granted to you'), enumerates what a mod is (tools/skills/rules/workflows/identities), and clarifies the grantee/scope distinction ('FULL payloads, for you as the grantee'). This makes it trivially distinguishable from siblings like grant_mod, revoke_mod, and create_mod.

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?

It notes that 'the same set is auto-injected at the task level', which hints at an alternative path, but it never states explicitly when to call this versus relying on injection or which sibling to prefer. The startup guidance for '*' lives in the schema parameter, not the description, so routing guidance here is only implied.

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