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

Goes well beyond the annotations: discloses the hashing behavior (hashes trimmed UTF-8 bytes of claim_note and returns the real digest), the rule against fabricating a hash, the caveat that a digest records the claim and not legal verification, the return field set, that it does not write a recipe, and that it never retries preparation. The only tension is that 'opens a session / queues a probe' reads as state creation while readOnlyHint=true, though the description's 'does not write a recipe' partially reconciles this.

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-loads the action, then handling of the rights claim, then return values, then alternatives. Dense but nearly every sentence earns its place; 'never fabricate a hash' and the digest caveat are slightly repetitive but justified for a compliance-sensitive field.

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 complex nested-object tool with no output schema and no schema descriptions, the description supplies return fields (session_id, probe_id, source_id, question_id, rights_claim, limits), the fallback path, and the retry caveat. Nothing an agent needs to invoke it correctly appears to be missing.

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?

With 0% schema description coverage the description must carry the load, and it does for the subtle nested parts: it explains claim_note (actual rights evidence or operator assertion) and claim_evidence_digest (an alternative, precomputed value). It leaves dataset_id, question, source.name, and source.url unexplained, though url is implied by 'HTTPS source' and the rest are self-evident.

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 specific verbs and resources: prepares an HTTPS source, opens a bounded research session, queues a source_inspect probe. It is clearly distinguishable from siblings probe_source (ask more) and get_source_inspection (recovery), and the return field list pins down what the call produces.

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?

Explicit routing: use probe_source with dataset_id/question_id/source_id to ask the prepared source more; use get_source_inspection if uncertain; and it notes this tool 'never retries preparation'. Both alternatives and the condition selecting them are stated.

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