AIDataParser

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

Goes well beyond the annotations (which only say non-readonly, open-world, non-idempotent, non-destructive) by disclosing that link creation charges nothing, payment happens on Stripe's page, credits never expire, and the post-payment page reveals the new API key. That is exactly the behavioral context an agent needs.

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 purpose, then packs pricing, credit semantics, and the key/email branching into compact sentences with no filler. Every sentence carries 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?

Although there is no output schema, the description explains what is returned (a checkout link to hand to the user) and what the user sees after payment. Combined with the conditional email/API-key logic, nothing needed to invoke it correctly 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?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: each enum value's price and credit amount, and the precise conditional role of `email` in relation to server API key state.

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 a specific verb and artifact ('Get a Stripe checkout link for a one-time credit pack') with the intended handling ('to hand to the user'). It is clearly distinguishable from siblings like check_credits and create_api_key.

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 covers the two usage branches: with an API key set the credits land on that account, without one pass the user's email. It also tells the agent to ask for the email rather than invent one, which is actionable routing guidance.

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 read-only, idempotent, and non-destructive behavior, so the description does not need to repeat those. The description adds valuable context beyond annotations by stating that the call is free and does not consume a credit, which is a meaningful behavioral detail for an agent deciding whether to invoke it.

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 a single concise sentence that front-loads the action and outcome. Every word contributes meaning, with no filler or redundant restating of the tool name.

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 zero-parameter read-only tool, the description fully covers what the agent needs: what is returned, which API key is involved, and the fact that the call has no cost. No output schema is present, but the described return value is simple enough that the agent can infer the response shape.

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 tool has zero parameters, so there is no parameter semantics to explain. Baseline 4 applies because no parameter information is needed for correct invocation.

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 states a specific verb ('Return') and resource ('number of extraction credits remaining on the authenticated API key'), which clearly distinguishes it from sibling tools like create_api_key or parse_document. The purpose is immediately obvious and unambiguous.

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 this tool is for checking credit availability and explicitly notes it is free and does not consume a credit, which helps an agent know it is safe to call at any time. It does not explicitly discuss alternatives, but none of the sibling tools serve a similar purpose, so the guidance is sufficient.

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?

The description goes well beyond the annotations (all false) by disclosing that the key is returned once and never shown again, instructing the agent to ask the user for their address, and stating the operation is free and does not consume credits. This is rich behavioral context that annotations do not provide.

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 condition, then explains the result, behavioral caveats, and configuration. Each sentence earns its place with no redundant or filler content.

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 single-parameter tool with no output schema, the description captures everything an agent needs: the one-time return, the need to store it, the address request, and the configuration instructions. It is fully self-contained.

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 already provides 100% coverage for the email parameter, describing account ownership and refusal for duplicate addresses. The description reinforces the need to provide the user's email and adds an actionable agent instruction ('Ask the user for their address'), which adds value beyond the schema but does not introduce new parameter semantics.

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 identifies the tool as the entry point for obtaining an API key when none exists. It states the verb (get/create), the resource (adp_live_ API key with 50 free credits), and differentiates from siblings by explaining it unlocks parse_document, parse_text, and infer_schema.

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 provides an explicit condition: 'Start here if you do not have an AIDataParser API key.' It also gives practical steps (provide email, configure as Bearer token) and notes the free cost, making it clear when and how to use the tool.

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 are all false, providing no safety profile, so the description carries the burden. It discloses the return structure ('JSON Schema plus a flat field list and an inferred doc_type'), the cost ('1 credit per successful call'), and the non-idempotent nature by implying a one-time inference followed by review. It does not explicitly discuss error conditions or side effects, but for a non-destructive inference tool, this is adequate. 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?

The description is three sentences with no fluff. The first sentence states the core function, the second provides usage guidance and workflow, and the third summarizes returns and cost. It is front-loaded with the purpose and each sentence earns its place. The structure is clear and scannable.

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?

The tool is moderately complex, but the description covers all essential aspects: the input (sample text), the output (schema, field list, doc_type), the workflow (infer, review, reuse), the cost, and the relationship to sibling tools. No output schema exists, so describing the return is the responsibility of the description, which it does. An agent has everything needed to call it correctly.

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%: all three parameters have descriptions in the input schema. The description adds marginal value by referring to the `text` parameter as the sample, reinforcing its role, but does not elaborate on `doc_type` or `instructions` beyond what the schema already provides. With full schema coverage, a baseline of 3 is appropriate; the description does not detract.

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 states a specific verb ('infer'), resource ('reusable JSON Schema'), and source ('a sample document's text'). It explicitly contrasts with the alternative of using a built-in schema_id, distinguishing it from parse_document and parse_text, which consume schemas rather than create them. The purpose is unambiguous and clearly differentiated from siblings.

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 when-to-use: 'Use this when no built-in schema_id fits', and then prescribes a workflow: infer once, review it, reuse as schema on parse_document/parse_text. It also mentions the cost implication, which is a practical constraint. No alternative is left unspecified, and the guidance is actionable.

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 and idempotentHint true, so the safety profile is covered. The description adds extra behavioral context: 'Free — does not consume a credit and needs no API key,' which is not in the annotations and is valuable for an agent deciding whether to call it. It also clarifies output content.

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?

Two sentences with no filler. The first sentence states the main purpose and output shape; the second adds cost/auth details. Everything earns its place and the most important info is front-loaded.

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?

There is no output schema, so the description must convey return structure. It says 'each with its id and the fields it extracts,' giving a reasonable mental model. It could be more explicit about whether the return is an array or object and how fields are structured, but for a simple list tool this is adequate. The zero-parameter complexity lowers the burden.

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 tool has zero parameters, so there is nothing to clarify. Per the baseline for empty parameter lists this is a 4. The description's mention of output fields (id and extracted fields) is about return values, not parameters, and does not detract.

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 says 'Return the built-in schema templates you can pass to parse_document as schema_id' — a specific verb, resource, and consumer. It also lists examples (invoice, receipt, resume) and distinguishes the output from sibling tools like infer_schema or validate.

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 clearly ties the tool to parse_document's schema_id parameter, implying when to use it: before calling parse_document to know available built-in templates. It does not explicitly say when not to use it or mention infer_schema as an alternative for custom schemas, but the context is strong enough.

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 annotations, it discloses 'Costs 1 credit per successful call', which explains the non-read-only billing side effect implied by readOnlyHint=false. It also reveals return fields (confidence score, review_needed flag) and schema-guaranteed output, which are absent from an output schema.

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 compact sentences front-load the core extraction behavior, then cover input mechanism, optional controls, return values, and cost. No filler or 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?

With no output schema, it correctly names return values, and all 7 parameters are covered by the schema. Missing operational details like conflict between url/base64 or file-size limits are minor and don't prevent correct invocation.

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 100%, and parameter docs already describe url, base64, media_type, schema, schema_id, redact, and instructions. The description only summarizes url/base64/schema/instructions without adding new semantics, so baseline 3 is appropriate.

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?

Description uses specific verb 'Extract' with clear resource 'PDF or image' and outcome 'clean, schema-guaranteed JSON', which differentiates from sibling parse_text. It tells agent exactly what tool does.

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 clearly scopes usage to PDF/image inputs and states input methods (url or base64) and optional schema/instructions. It doesn't explicitly say when to choose parse_text or when not to use this tool, 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.

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

Annotations are all false and offer no behavioral signal, so the description carries the burden. It adds valuable context: output is schema-guaranteed, returns a confidence score and review_needed flag, and costs 1 credit per successful call. It does not mention error behavior or side effects, but the core operational behavior is disclosed.

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?

Every sentence earns its place: use-case, parameter pointer, sibling routing, optional parameters, return shape, and cost. It is front-loaded with the core purpose and remains readable despite covering multiple facets.

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?

With five parameters, nested schemas, and no output schema, the description does well by explaining the return envelope (data plus confidence and review_needed) and the credit cost. It could slightly improve by outlining failure/validation behavior, but the essential information for invoking the tool correctly is present.

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%, so the baseline is 3. The description lightly reinforces the roles of text, schema, schema_id, and instructions, but adds little beyond the schema itself. 'Ignored when schema is provided' is already stated in the schema, so no extra semantic weight is gained.

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 a precise verb+resource ('Extract clean, schema-guaranteed JSON from raw/messy text') and lists concrete input types (scraped content, email bodies, chat logs, OCR, tables). It also explicitly distinguishes itself from parse_document, so an agent can pick it correctly without inspecting siblings.

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?

Directly says 'Use this instead of parse_document when you don't have a file', giving an explicit when-to-use rule and naming the alternative. The list of supported text sources further clarifies appropriate contexts.

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 are sparse (only readOnlyHint/idempotentHint/destructiveHint), so the description carries real load: it discloses the 3-calls-per-day rate limit, the 4000-character cap, the no-API-key/no-email/no-signup auth requirement, and the exact return payload (structured data, confidence, review_needed flag). These are concrete operational facts an agent cannot get from structured fields.

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, front-loaded with the value proposition, then the input contract, then the return shape and escalation path. No filler, no restatement of the title.

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?

With no output schema, the description compensates by naming the returned fields and their parity with the paid tools, and it covers limits, auth, and alternatives. For a 4-parameter extraction tool this is sufficient to call correctly.

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%, so baseline is 3. The description adds example text types (invoice, receipt, resume, scraped HTML, email body) and frames schema/schema_id as constraining the result, but it never mentions the `instructions` parameter at all, so it does not meaningfully exceed what the schema already documents.

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 a specific verb and resource ('Run a REAL extraction', parse messy text into JSON) and immediately frames it against the paid siblings parse_text/parse_document. An agent can tell this is the zero-auth trial path without opening any schema.

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 when-to-use (see output shape before committing), when-not (real volume), and the exact alternative route ('call create_api_key for 50 free credits, then use parse_text or parse_document'). It also points to list_schemas for the schema_id set. Nothing is left to inference.

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 indicate read-only, idempotent, and non-destructive behavior; the description adds useful context: result contains a valid flag plus per-field errors, and the call is deterministic, free, and key-less. 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?

Two sentences with no filler: the first explains operation and results, the second gives usage context and cost/side-effect guarantees. Key information is front-loaded and every clause earns its place.

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 read-only validation tool, the description covers return format, use cases, and behavior sufficiently, and annotations cover the safety profile. It does not explain behavior when neither schema nor schema_id is supplied, but this is a minor edge case given the schema marks them optional.

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 100%, so the schema already documents all three parameters, including schema taking precedence over schema_id. The description only lightly maps schema_id to 'built-in template' without adding new semantic detail, so the baseline 3 is appropriate.

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 ('check whether') and names the exact resource ('JSON object' vs. a 'JSON schema' or 'schema_id template'), plus the output shape ('valid flag plus per-field errors'). It is clearly distinct from siblings like parse_document or infer_schema, which perform different operations.

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 gives concrete conditions: verify data you already hold from a prior parse result, own output, or upstream feed, before acting or spending credits. It implies not for parsing or extracting data, though it does not explicitly name alternative tools or exclusions.

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