mindee

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

The annotations only cover readOnly/destructive/idempotent hints, so the description adds crucial behavior: the tool enqueues an inference, polls up to ~30s, and returns a job_id if still running. It also discloses that it consumes Mindee API credits billed per page, which is not available in annotations. No contradiction with the annotations; readOnlyHint=false aligns with the enqueue/submit action.

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 compact: one sentence for the core action, one for input alternatives, one for async behavior, and one for cost/API details. Every sentence adds distinct information without redundancy.

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 10 parameters and no output schema, the description covers the submission flow, input modes, polling behavior, fallback job_id, cost implications, and API endpoint. It also names the sibling tools for polling and reading results, giving the agent a complete mental model of how to handle the response.

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 100%, but the description adds the critical constraint that document_url and file_base64 are mutually exclusive ('Provide EITHER document_url (a public URL) OR file_base64 (+ filename)'). It also clarifies that filename is for file_base64 uploads, complementing the schema's individual parameter descriptions.

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 'Submit a document (PDF or image) to a Mindee extraction model and return the structured fields,' clearly stating the verb and resource. It distinguishes itself from siblings by describing the enqueue/poll flow and referencing mindee_get_job and mindee_get_inference for follow-up, making its unique role among the listed tools unmistakable.

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 tells the agent to provide either document_url or file_base64, and explains that if processing isn't complete it returns a job_id to poll with mindee_get_job then read with mindee_get_inference. This gives explicit when-to-use guidance and names the alternative tools for subsequent steps. It also notes the paid API credits, which is a practical consideration for deciding to invoke.

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, and the description adds value by specifying the return format as a 'compact map of extracted fields (plus raw_text if it was requested)'. This goes beyond the annotation's safety indication, providing useful output expectations. No contradiction exists.

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 two sentences with the main action front-loaded, followed by a concise output description and API endpoint. Every sentence provides necessary information without fluff.

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 simple retrieval tool with 2 parameters, the description covers the action, output shape, and endpoint. It does not explain error handling or pagination, but these are not critical given the tool's simplicity and the presence of annotations. The return format detail adds completeness.

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 100% with both parameters described (inference_id and raw). The description mentions 'by id' which aligns with the inference_id parameter but does not add significant new semantics beyond the schema. The mention of raw_text in the output is not directly a parameter detail.

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 fetches the structured result of a completed inference by ID, using specific verbs ('Fetch') and a specific resource ('structured result of a completed inference'). It distinguishes itself from siblings like mindee_get_job (job status) and mindee_extract_document (submission) by focusing on the result retrieval.

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 implies usage after an inference is completed ('completed inference'), giving clear context on when to call it. It does not explicitly mention alternatives or when not to use it, but the purpose is distinct enough from sibling tools to guide selection.

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 establish readOnlyHint=true and openWorldHint=true. The description adds significant behavioral context: it enumerates the possible statuses (Waiting, Processing, Processed, Failed) and explains that a Processed response includes a result_url, which is a key behavioral detail not present in the 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 concise and well-structured: a one-sentence purpose, a list of status values, a note on the result_url, and the API endpoint. Every sentence adds value and there is zero redundant information.

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 simple one-parameter status tool with no output schema, the description covers the essential workflow: statuses, the result_url on Processed, and the next tool to use. It does not specify error handling or response structure for non-Processed statuses, but given the read-only nature and single parameter, it is sufficiently complete.

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 schema description covers job_id fully, explaining it is returned by mindee_extract_document or an enqueue call. The tool description only restates 'by job id' and includes it in the URL pattern, adding no extra parameter semantics beyond what the schema already provides.

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's function: 'Check the processing status of an enqueued document by job id.' It distinguishes itself from siblings by explaining the relationship to mindee_get_inference, which is used after processing completes, making the purpose distinct.

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 context on when to use this tool (to poll status after enqueue) and explicitly names the alternative for the next step (mindee_get_inference). It does not explicitly list exclusions, but the workflow guidance is clear enough for an agent to select appropriately.

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?

Read-only behavior is already covered by readOnlyHint=true. The description adds account scoping ('available to your Mindee account'), return fields, and the API endpoint, providing useful context without redundancy. No contradiction 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?

Three sentences, each with purpose: statement of action, usage of the returned id, and API reference. 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?

Despite no output schema, the description lists the items' fields (id, name, type) and explains how to use the result. Combined with high-quality annotations and schema, it's sufficient for a simple list operation.

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 already fully describes both optional parameters with examples (name filter, model_type filter). The description adds no additional parameter semantics, so baseline 3 applies.

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 lists document-extraction models for the account, specifying returned fields (id, name, type). It distinguishes from sibling tools like mindee_extract_document by focusing on discovery, and explicitly ties the model id to that extraction 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 indicates when to use it: to discover available models and obtain the id for use with mindee_extract_document. It does not explicitly state exclusions or alternatives, but the context is clear.

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