get_user_domain_verification_status

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

The readOnlyHint annotation already covers the safe-read profile, and the description consistently matches it. It adds context beyond the annotations: an account or key prerequisite and the important detail that 'a session opens this tool,' meaning the data is scoped to an authenticated session. It does not mention rate limits, caching, or whether status can be polled repeatedly, but the auth behavior is substantive.

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 purpose is front-loaded in the first sentence, followed by a clearly separated ACCESS block. Both parts are short, and the second part is operational rather than filler. The only inefficiency is that the access instructions could be terser, but they are directly relevant to successfully invoking the tool.

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 a single required parameter, a readOnly annotation, and an output schema that documents the returned challenge details, the description covers what an agent needs to call the tool successfully. The remaining gap is disambiguation from similarly named verification-status siblings. In a server with roughly 130 tools, that keeps it short of a 5.

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?

The input schema has 100% description coverage for the single parameter, so the baseline is 3. The description adds no meaning about the session_id beyond what the schema already says, such as whether it comes from start_user_domain_verification or how an invalid ID behaves. The schema does the heavy lifting here.

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 names a specific verb and resource: 'Get the current status of a domain verification session, including challenge details.' That is clearer than a bare restatement of the name, and it adds the useful detail that challenge data is returned. However, among the many near-identical siblings in this server (check_domain_verification, check_user_domain_verification, start_user_domain_verification), nothing in the description tells the agent which one this tool is not.

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 ACCESS block provides real usage guidance: the tool requires a Proof account, an API key, or a login session, and the description says to restart the server or use start_login, then retry. However, it gives no guidance on when to choose this tool over the domain-verification siblings, or whether it is the polling counterpart to start_user_domain_verification. Usage guidance is implied by the sibling naming rather than stated explicitly.

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