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

Goes well beyond the annotations: it discloses the response contents (characters recorded, redaction count), a self-verification retry rule, the prohibition on credentials, the approval gate on first report, and that the action 'grants nothing'. The one ambiguity is that readOnlyHint=true sits uneasily with a tool that creates or updates a page in Rithmo, though the 'grants nothing' clause signals the intent is declarative reporting rather than mutation.

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 and nothing is irrelevant, but it is a single dense paragraph of roughly 250 words mixing sourcing rules, retry logic, gating, secrets policy, and the host-adapter protocol. Repeated insistence ('every line, never summarized, shortened or reworded, however long') adds emphasis rather than information, and the host-adapter sentence could be split out or trimmed.

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 tool with 16 parameters, nested host-protocol objects, and no output schema, the description is unusually complete: it explains the return payload, the retry condition, the approval prerequisite, and the 'unknown, never empty' convention for unreadable data. Only the v1 host-adapter surface (scope, permissions, resources, mcp_connections) is left to the schema alone.

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 already 75%, so the schema carries most of the load, but the description still adds real meaning beyond it: instructions must be verbatim and complete, agent_key identifies which agent, tools are names-only with has/denied access, and unknown fields must be 'unknown' rather than empty. It does not cover every one of the 16 parameters (e.g. scope, permissions, resources get no prose), which keeps it off a 5.

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 opening sentence names a specific verb and resource — report what you are instructed to do plus the tools and knowledge you have — and explains the effect ('your page in Rithmo shows you as you are and flags when that changes'). It is clear enough to distinguish from get_my_setup, but it never names update_agent or register_my_agent, so the agent must infer the boundary from the naming alone.

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?

Explicitly states when to call ('at the start of every run, with agent_key'), the branching condition ('If Rithmo has an instructions file for you, send only your tools'), the mandatory path ('If Rithmo has no instructions file for you, this report is required'), and the consequence of not calling (check_premises holds you after 15 minutes or on drift). This is exactly the when/when-not/alternative structure the dimension rewards.

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