hypathesis

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

Even with annotations indicating idempotent and read-only, the description adds critical context: the polling mechanism, possible return states (pending/complete/error), and the returned api_key usage. No contradictions with annotations.

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 description is well-structured with labeled sections (Args, Returns) and front-loaded purpose. Every sentence adds value, with no wasted words.

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 the tool's simplicity (one parameter, no nested objects), the description fully covers all necessary aspects: purpose, usage sequence, parameter source, return types, and error handling. The output schema is documented inline, leaving no gaps.

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 fully compensates by explaining the sole parameter 'user_code' as 'The user_code returned by initiate_device_auth', adding essential context not present in the schema.

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 uses a specific verb-resource pair ('Check if the user has completed browser sign-in') and clearly distinguishes this polling tool from the sibling 'initiate_device_auth' by stating it should be called after that.

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 use ('Poll this after calling initiate_device_auth'), implying not to use before. This provides clear context for selection among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful context beyond this by listing the possible status values (Processing, Ready, Empty, Ineligible, Pending), explaining the polling loop expectation, and documenting auth/session options.

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 description is well-structured and front-loaded with the core purpose, followed by a one-line usage directive and compact Args/Returns sections. Every sentence adds needed information; there is no filler or repetition.

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 3-parameter polling tool with an output schema, annotations, and documented auth variants, the description covers all essential context: why to call it, how to call it repeatedly, what each argument means, and what status values signal completion. Nothing needed for correct invocation is 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 fully compensates by explaining each parameter: file_id comes from /upload, authorization is an optional API key with a concrete format, and session_token is optional for anonymous uploads. This is far more informative than the bare schema names and defaults.

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 opens with a clear verb+resource pair, 'Check the processing status of an uploaded paper,' which precisely defines the tool's function. It also distinguishes this from the sibling get_variable_relationships by framing this as the prerequisite polling step for that tool.

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 description gives an explicit workflow: poll after uploading a PDF until status is 'Ready' before calling get_variable_relationships. This clearly states when to use the tool and how it relates to the alternative/downstream sibling, leaving no ambiguity about its place in the process.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses the status gate, the anonymous-vs-authenticated response difference, and the sign-up action needed for full access. It is consistent with annotations and leaves no surprising mutation behavior.

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 description is front-loaded with a one-sentence purpose, then uses compact Args/Returns blocks. Every paragraph adds a distinct piece of information: readiness, auth handling, parameter origins, and response shape.

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 one required parameter, two optional auth parameters, and an output schema, the description supplies everything needed to call it correctly and interpret the result. The only omitted detail, behavior when status is not Ready, is safely implied by the explicit precondition.

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 0%, so the description carries the full parameter burden. It explains file_id's origin (/upload endpoint), authorization's accepted formats ('Bearer hk_...' or 'hk_...'), and session_token's role for anonymous uploads.

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 the exact operation ('Retrieve analyzed variable relationships') and scopes it to 'a completed paper'. It also explicitly references get_analysis_status, distinguishing this tool from the status-checking sibling.

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 states the readiness precondition ('Only returns results when get_analysis_status reports status="Ready"'), which tells an agent when calling will be productive. It also provides clear auth-mode guidance: anonymous calls get gated results, while API-key calls get full details.

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

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

Discloses return values (verification URL, user_code, expires_in, message) and that it starts a sign-in flow. Annotations are neutral; no mention of side effects like invalidating previous auths.

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?

Description is brief: one sentence for purpose, two sentences for usage guidance, and a sample return. No unnecessary words.

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?

Tool has no parameters and a clear output; description covers the flow and return format completely, including subsequent step to poll check_device_auth.

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?

No parameters in input schema, so description does not need to add meaning. Schema coverage is 100% (empty schema is fully described by absence).

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 clearly states the tool starts a browser-based sign-in flow to get an API key for full access. It differentiates from sibling tools like check_device_auth (polling) and analysis tools.

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 says 'Call this when you need detailed analysis results that require authentication' and instructs to poll check_device_auth after user signs in.

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