Claix

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds the is_agent_mode prerequisite, the return fields (data[], agent_data, log_id), and the cita_por_campo output shape, which is useful context beyond the annotations. No contradiction with annotations is present.

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?

Four short sentences deliver purpose, prerequisite, return shape, and a conditional output format with no filler. Every sentence earns its place and the key scoping information 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?

The definition covers purpose, supported file types, a required mode, and key output behavior, while the input schema handles all six parameters and the output schema handles return values. The main gap is that is_agent_mode is never explained or mapped to a parameter, and schema examples mention PDF despite the description listing only document formats.

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%, with detailed per-parameter explanations, so the baseline is 3. The description does not need to repeat parameter semantics, and while it mentions cita_por_campo, that is not an input property, so it does not add parameter-level guidance.

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 action ('Run document extraction plus Agent mode reasoning') and a specific resource type (.docx/.txt/.md/.rtf). The phrase 'plus Agent mode reasoning' distinguishes it from the plain claix.extract.doc siblings, and the extension list differentiates it from claix.agent.pdf/image/excel/text.

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 a clear precondition ('Requires is_agent_mode') and lists the supported file types, which helps an agent know when this tool is applicable. It does not explicitly name a fallback alternative for extraction without agent mode, but the context is clear enough to route correctly.

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 discloses the return fields ('data[], agent_data, and log_id') and the conditional value shape when 'cita_por_campo is true', both beyond the annotations. It also states the schema-flag requirement; the annotations already cover read-only/idempotence, and nothing in the main description contradicts them.

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 short sentences, each earning its place: purpose, prerequisite, and return/citation behavior. Information is front-loaded with purpose before technical conditions.

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 rich schema and existing output schema, the description covers the tool's purpose, schema requirement, and key output behavior. Minor gap: it does not clarify where 'cita_por_campo' is set or explicitly address how the file source parameters should be combined (though schema descriptions cover individual parameters).

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 every parameter; baseline of 3 applies. The description adds no parameter-level guidance, and the reference to 'cita_por_campo' is not an input parameter of this 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?

States a specific action ('Run Excel/CSV extraction') plus the distinguishing 'Agent mode semantic reasoning', with the title confirming Excel/CSV to JSON. It does not explicitly name the sibling claix.extract.excel as the non-agent alternative, so the differentiation is implicit rather than explicit.

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 only usage guidance is the precondition 'Requires is_agent_mode on the schema', which tells the agent when the tool is applicable but not what to use when that flag is absent. There is no mention of claix.extract.excel as the plain-extraction alternative, so when-to-use is implied rather than stated.

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 readOnly/idempotent/non-destructive behavior. The description adds a mandatory runtime flag (is_agent_mode) and a conditional output schema (cita_por_campo), which are behavioral traits not present in the annotations. This is valuable supplementary context. No contradiction.

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-loading the purpose, then requirement, then output behavior. Every sentence carries information, with no fluff. It could be slightly more explicit about what 'agent mode reasoning' entails, but that is not verbosity.

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 has an output schema and well-documented parameters. The description covers the main behavioral requirements (is_agent_mode) and output structure (data[], agent_data, log_id, and conditional field format). It doesn't explain how to enable is_agent_mode or what agent mode reasoning means, which is a notable gap for an agentic tool.

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 baseline is 3. The description does not explain the six schema parameters further; it references 'is_agent_mode' and 'cita_por_campo', which are not input parameters, so it adds no parameter-specific meaning.

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 action ('Run image extraction plus Agent mode reasoning') and the title clarifies the output format (image to JSON). This distinguishes it from claix.extract.image (extraction without agent mode) and other claix.agent.* tools for different file types, though it doesn't name them explicitly.

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 notes a precondition ('Requires is_agent_mode') and describes the output shape, but it does not explicitly state when to prefer this over claix.extract.image or when agent mode is unnecessary. Usage context is implied but not made 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?

With readOnlyHint, idempotentHint, and destructiveHint already covering the safety profile, the description adds value by disclosing the return shape (structured data[], agent_data, log_id) and the conditional cita_por_campo behavior. It does reference is_agent_mode without that parameter appearing in the schema, but this is a gap in explicitness rather than a contradiction of 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?

Three short sentences, all informative, front-load the core operation and then give the return contract. There is no filler, repetition of schema fields, or unnecessary detail.

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 return contract and cita_por_campo behavior are covered, and the schema documents parameters thoroughly. However, for a tool with many sibling variants, the description does not explain how to choose it over claix.extract.pdf or how is_agent_mode is supplied, leaving important selection and setup context to inference.

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 all six parameters are already well documented and the description does not need to compensate. It only mentions cita_por_campo, which is not an input property, so it adds no meaningful parameter semantics beyond 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?

States a distinct operation ('Run PDF extraction plus Agent mode reasoning') on a specific resource (PDF), and the 'Agent mode' qualifier separates it from plain extraction tools like claix.extract.pdf. It does not explicitly name a sibling, but the wording and title make the intent clear.

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 a prerequisite ('Requires is_agent_mode') but no explicit when-to-use guidance or alternatives. It never tells the agent when to prefer this over claix.extract.pdf or when plain extraction would suffice, so usage context is only implied by the title and naming.

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 discloses the endpoint, return fields (data[], agent_data, log_id), and the conditional {value, source} shape when cita_por_campo is true—all beyond the annotations' safety flags. It also states the input must be content, not a file. No contradiction with readOnlyHint or idempotentHint is present.

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 short sentences front-load the purpose and then pack prerequisite, input form, return shape, conditional behavior, and endpoint into the remaining text. 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?

The definition covers the core invocation path and return contract, and the output schema supplies the detailed response shape. However, it leaves 'is_agent_mode' unexplained (how to ensure it is on) and gives no guidance for choosing this tool over claix.extract.text or the other agent tools. For a 4-param read-only transform this is adequate but not rich.

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?

Parameter coverage in the schema is 100%, so the description does not need to redefine api_key, content, space_id, or schema_id. It adds only a reminder that content must be sent inline rather than as a file, which mostly restates the schema. Baseline 3 is appropriate because the schema carries the parameter documentation.

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 operation ('Run text/HTML/XML extraction plus Agent mode reasoning') and resource ('text/HTML/XML to JSON'), and the title/mode clearly separate it from the claix.extract.* and other claix.agent.* siblings by content type. 'Send content (no file)' further disambiguates it from file-based agent 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?

It gives a clear precondition ('Requires is_agent_mode') and input format ('Send content (no file)'), but it never names an alternative or states when to prefer claix.extract.text or another sibling. Usage is implied rather than explicit, so an agent must infer when this tool is appropriate.

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 cover safety (readOnly, idempotent, non-destructive). The description adds behavioral context: it requires a schema_id (dependency) and returns base64-encoded xlsx. It also clarifies the file_base64 input should be a .json file, which the schema description ambiguously refers to as PDF/image. 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 concise sentences: purpose, input method, and return format. Front-loaded with the primary action, no fluff 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 6-param tool with an output schema, the description covers the core workflow (convert JSON to Excel), input options, and output. It doesn't explain the schema concept in depth, but that is referenced and the schema_id is documented in the schema. Given output schema exists, return values are sufficiently covered.

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%, giving a baseline of 3. The description adds meaning by explicitly stating json_data and file_base64 are alternative inputs ('or'), and clarifies that file_base64 should be a .json file, which is not clear from the schema description. This goes beyond 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 clearly states the tool converts JSON to an Excel .xlsx file using a Claix schema, with a specific verb and resource. It distinguishes from sibling extract/agent tools by focusing on JSON-to-Excel conversion.

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 clear context on how to use the tool (provide json_data inline or file_base64 with a .json file) and the return format. It doesn't explicitly name alternatives or when-not-to-use, but the use case is unambiguous given sibling tools are extract/agent tools.

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 annotations, the description adds 'Irreversible,' 'Free call,' the success response shape, and specific 404 conditions, all of which materially inform an agent's decision to invoke this destructive tool. It fully aligns with the destructiveHint and idempotentHint 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?

Every sentence in the description earns its place: the operation, the HTTP route, parameter constraints, success response, irreversibility, cost, and error semantics. It is compact, front-loaded, and free of filler.

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 two-parameter destructive tool, the description covers invocation, success behavior, failure conditions, cost, and side effects. The output schema and parameter descriptions in the input schema cover the remaining structured details, making this definition effectively 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 input schema already has 100% description coverage, so the baseline is 3. The description adds extra semantic value by clarifying that document_id is a path parameter and that no body or query parameters are accepted, which is not evident from the schema alone.

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 and resource: 'Delete a persisted document by document_id,' and reinforces it with the exact HTTP path (DELETE /delete-document/{document_id}). This clearly distinguishes the tool from siblings like claix.schemas.delete by targeting persisted documents rather than schemas.

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 intended use is clear: delete a persisted document when its document_id is known. It does not explicitly name alternatives or exclusions, but it provides strong operational guidance by stating there are no body/query parameters and by explaining the 404 behavior for missing, foreign, or already-purged documents.

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?

Adds useful behavioral detail beyond the annotations: returns log_id, conditional output shape when cita_por_campo is true, a file size limit, and legacy .doc exclusion. It does not describe asynchronous behavior or retrieval of the log_id, but it does not contradict the readOnly/idempotent 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 filler: purpose and supported formats first, then return behavior, then the conditional output shape and the .doc exclusion. Every sentence 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?

Given the detailed input schema, existing output schema, and safety annotations, the description is complete enough for an agent to call the tool correctly. It covers supported inputs, constraints, output handle, and the key unsupported case without relying on external knowledge.

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?

All six parameters already have rich descriptions in the schema (100% coverage), so the description is not required to add parameter-level meaning. The file-format and size constraints add useful context but do not define any specific parameter beyond what the schema 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?

States a specific verb ('Extract'), resource ('Word document'), output ('structured JSON'), and supported file types (.docx, .txt, .md, .rtf) with a size cap. The format list and 'doc-json schema' clearly distinguish this from sibling extract tools for PDF, Excel, image, and text.

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?

Provides clear invocation context: accepted formats, the 10 MB limit, and an explicit when-not ('Legacy .doc is not supported'). It does not explicitly name alternative sibling tools for other formats, but the format-based guidance is enough for an agent to route most requests correctly.

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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavioral context beyond annotations: it processes only the first sheet, returns 'typed JSON matching the schema plus log_id', and explains the cita_por_campo conditional that changes field shape from bare values to {value, source}. This helps the agent set correct expectations. It stops short of 5 because it omits edge-case behavior like file size limits, CSV encoding assumptions, or multi-file handling.

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?

Five sentences, with the core purpose front-loaded in sentence one, followed by high-value constraints (first sheet only), return format, conditional behavior, and usage trigger. Every sentence carries meaningful information and is ordered by importance. It is slightly longer than strictly necessary but earns its length; a 5 would require even tighter phrasing.

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 has an output schema (so return values need not be fully re-explained), 6 parameters with 100% schema coverage, and strong annotations, the description covers the essential gaps: file-type scope, sheet limitation, output shape, and the cita_por_campo condition. Nothing critical for correct invocation is missing. It is not a 5 because it could briefly clarify the relationship between file_base64 and file_path (e.g., 'provide exactly one') to prevent ambiguous calls.

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 documentation carries the parameter-semantics burden and the baseline is 3. The description adds marginal value by mentioning cita_por_campo, which provides semantic context for how schema_id affects output shape, but it does not add format, precedence, or exclusivity rules for the file input parameters (file_base64 vs file_path) beyond what the schema already states.

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-resource pair ('Extract structured JSON from an Excel (.xlsx) or CSV file') and names the schema-driven mechanism ('using a Claix excel-json schema'). It differentiates from sibling tools like claix.extract.pdf, claix.extract.doc, claix.extract.image, and claix.extract.text by explicitly scoping to spreadsheets/CSVs. The 'first sheet only' detail further sharpens the operational scope.

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 final sentence gives an explicit trigger condition: 'Use when the user attaches a spreadsheet or CSV.' This tells the agent when to select this tool. However, it does not name alternatives explicitly or state when NOT to use it (e.g., pointing to claix.extract.pdf for PDFs or claix.convert.json_to_excel for the reverse direction), so it stops short of a 5.

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. The description adds valuable behavioral context by noting the return value is log_id and that cita_por_campo changes the output shape to {value, source}. 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 compact sentences front-load the core action, constraints, and primary use cases. Every sentence earns its place and there is no redundant restatement of schema fields.

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 moderately complex extraction tool, the description covers formats, size, use cases, return value, and conditional output shape. The mention of cita_por_campo is slightly under-specified (it is not an input parameter), but an output schema exists and the schema covers the parameters, so the definition is largely 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?

Schema description coverage is 100%, with each parameter already documented including examples. The description does not add parameter-level meaning, but it does add useful output-related context not present in the schema. Baseline 3 is appropriate given the schema carries the parameter documentation burden.

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 and resource: 'Extract structured JSON from a visible image' with concrete formats and size limits. It also names intended use cases ('photos of documents, tickets, or labels'), making it easy to distinguish from sibling extract.* 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?

It gives clear usage context by specifying supported image types, size, and typical document/receipt/label use cases. However, it does not explicitly mention when NOT to use this tool or name alternative extract.pdf/extract.text options for non-image inputs.

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 declare readOnlyHint=true, but the space_id parameter description says the document is saved ('el documento se guarda') and can later be queried with claix.space_context.ask. That is a state-changing side effect and directly contradicts the read-only annotation, so the contradiction rule applies.

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 front-loaded sentences with no padding. Purpose, return shape, conditional behavior, and use cases all earn their place, and the schema reference is necessary to identify the extraction contract.

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 rich input schema and an existing output schema, the description covers the essential operational facts: file type, size cap, return object, cita_por_campo behavior, and use cases. It is slightly less complete because the save-to-space side effect appears only inside a parameter description and conflicts with the readOnly annotation.

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 provides thorough descriptions for all six parameters, reaching 100% coverage. The main description adds no parameter-level meaning; cita_por_campo is the only extra behavioral detail and it describes the output shape rather than an input parameter.

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 action ('Extract structured JSON from a PDF') and resource class ('Claix pdf-json schema'). It also specifies 'text or scanned' and 'max 15 MB', clearly distinguishing it from sibling extract.doc/excel/text/image 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?

The description names concrete use cases ('invoices, contracts, forms, or reports') and the PDF format boundary. However, it does not explicitly say when to prefer a sibling extract tool over this one, so it stops short of full when/when-not 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?

Beyond the annotations (read-only, idempotent), it discloses the POST endpoint, payload size cap, the log_id return value, and the cita_por_campo {value, source} output shape. These add operational context not present in the structured 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?

Four short sentences front-load the core action, then pack operational constraints (no file, max chars, return value, conditional output, endpoint) with no repetition or filler.

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?

Combined with the rich input schema, output schema, and safety annotations, the description covers input format, size limits, endpoint, and return behavior. There are no obvious missing call requirements for an agent to invoke 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% and the schema already provides detailed descriptions and examples for api_key, content, space_id, and schema_id. The description adds extra meaning for content by specifying it must be sent inline, not as a file, and capped at 300,000 characters, so it rises above the baseline.

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 specific verb ('Extract') and resource ('already processed plain text, HTML, or XML'), and specifies the output ('structured JSON') and schema type. It clearly separates this tool from file-based siblings like claix.extract.pdf/doc, especially with 'no file'.

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 tool is for already-processed text/HTML/XML rather than raw files, and reinforces with 'Send the payload in the content field (no file)' and a 300k character limit. It doesn't explicitly name sibling alternatives or when-not-to-use, but the context is clear enough for an agent to select this over claix.extract.pdf/doc/excel/image.

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 cover the read-only/idempotent/destructive profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds some context like the POST endpoint and 'Persistent Mode' for window_time infinity. However, it does not disclose side effects such as creating a persistent resource, authentication requirements, or what happens on duplicate calls beyond what annotations imply.

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 dense sentence that front-loads the endpoint and then clearly separates required from optional parameters. There is no redundant phrasing, though the sentence runs long and mixes reading levels with English and Spanish parameter names.

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 10-parameter tool with nested objects and an output schema, the description covers the essential required/optional split and key edge-case semantics. It omits api_key and conditional requirements like 'agent_definition required if is_agent_mode', but the schema fully documents those, so the description remains sufficient as a high-level guide.

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 baseline is 3. The description adds value by organizing parameters into required vs. optional and clarifying specific semantics: type enum values, window_time minutes or 'infinity', and cita_por_campo as source verification. This is a useful summary beyond the raw 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 states a specific verb ('Create') and resource ('Claix schema') and includes the HTTP endpoint, making the action unambiguous. It clearly differentiates this tool from siblings like claix.schemas.list and claix.schemas.delete.

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 defines what the tool does but does not explicitly state when to prefer it over alternatives or mention exclusions (e.g., json-excel cannot use Agent mode, a constraint found only in the schema). Usage context is implied by the tool name and sibling names rather than articulated in the description.

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 destructiveHint=true and readOnlyHint=false, so the description need not repeat safety. However, description adds context about ownership and the specific endpoint. It does not disclose side effects (e.g., permanence, dependent resources) beyond what 'delete' implies. Since annotations cover the destructive nature, the description adds modest value.

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 short sentences. The first sentence immediately states the action, object, and endpoint; the second highlights the required parameter. No filler or redundancy. Every word serves a purpose.

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 (delete a schema by ID), the description is complete enough: it defines the operation, the scope, and the requirement. An output schema exists, so no need to explain return values. Slight omission: does not explicitly state that deletion is permanent, but destructiveHint true covers that. Overall adequate for a straightforward delete tool.

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 provides 100% coverage for both parameters, including detailed descriptions and examples. The description only mentions 'schema_id' as required, which adds no new semantic meaning beyond the schema. With high schema coverage, the description is adequate but not enriched.

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 action: 'Delete a Claix schema'. It specifies the HTTP method and endpoint (POST /api/delete-schema) and scopes the deletion to schemas 'owned by the API key'. This unambiguously distinguishes it from siblings like claix.schemas.create and claix.schemas.list.

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 a prerequisite ('Requires schema_id') but does not explicitly state when to use this tool versus alternatives or when not to use it. It does not mention looking up schemas first (though the schema parameter description does). Minimal guidance beyond the requirement.

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, idempotentHint, and non-destructive behavior, so the safety profile is well covered. The description adds context by mentioning the authenticated account and enumerating the exact return fields (id, name, type, etc.), which goes beyond 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 two sentences, front-loaded with the primary action and return fields, followed by the usage instruction. Every sentence adds value with no redundancy or filler.

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 list tool with an output schema and strong annotations, the description is complete. It states the resource, authentication context, return fields, and when to call it, leaving no significant gaps for an agent to select and invoke 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?

The input schema has 100% description coverage for the single api_key parameter, so the baseline is 3. The tool description does not add any parameter-specific meaning beyond what the schema already provides, but it doesn't need to given the schema's completeness.

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: 'List the Claix schemas available for the authenticated account.' It specifies the verb and resource, lists the returned fields, and explicitly positions itself as a prerequisite for claix.extract.* and claix.agent.* tools, distinguishing it 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 provides explicit usage guidance: 'Call this first whenever you need a schema_id before claix.extract.* or claix.agent.* tools.' This tells the agent when to use this tool relative to its siblings and establishes a clear workflow.

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 mark this as read-only, idempotent, and non-destructive; the description adds genuine behavioral context beyond those hints: answers are built by cross-referencing documents, log_id is null when no document contains the answer, and verif_space enriches responses with {value, source} items. This gives an agent realistic expectations about edge cases.

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 information-dense but well structured: the core action is front-loaded, the sibling comparison follows, and constraints and return semantics are packed into later sentences without redundancy. Every sentence 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 tool with an output schema, no nested objects, and helpful annotations, the description covers everything an agent needs to call it correctly: input limits, space_id origin, behavioral distinction from the sibling, return fields, and the verif_space-dependent output shape. There are no significant 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?

Schema coverage is 100%, so the schema already documents api_key, space_id, and questions. The description adds meaning beyond that by explaining that space_id is 'the same one passed as the optional space_id when extracting,' which links this call to other tools and helps the agent select the correct value. The max-question and max-length limits are already in the schema, so the added value is modest but real.

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 and resource ('Ask up to 5 questions across every document grouped in a knowledge space') and immediately differentiates itself from claix.window_context.ask by emphasizing cross-document comparison. It clearly tells an agent what this tool does and how it differs from its closest 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?

The description explicitly states when to use this tool ('use it to compare, add up, or reconcile data spread over several files') and contrasts it with the single-document sibling. It also clarifies the required space_id provenance, tying it to the optional space_id used during extraction.

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 convey non-read-only and non-destructive behavior. The description adds meaningful context: the HTTP endpoint (POST /create-space), the exact response fields, that it is a free call, and how the returned space_id should be used downstream. This goes beyond what annotations 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?

Three concise sentences cover purpose, endpoint, return values, workflow, and cost. The inaccurate 'only field is name' sentence is a defect, but the description is otherwise tight and well-structured.

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 simple, has an output schema, and the description covers the creation workflow and follow-up usage. It misses nothing critical, but the parameter inaccuracy prevents a perfect score.

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 baseline is 3. However, the description states 'The only field is name,' which contradicts the schema that also defines an optional api_key parameter. This is actively misleading and lowers the score despite the schema being complete.

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 action: 'Create a knowledge space to group persisted documents', names the resource, gives the endpoint, and lists return values. It also references claix.space_context.ask, which helps distinguish this from sibling tools like claix.spaces.delete.

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 workflow guidance: create a space, pass the returned space_id when extracting, and query the group with claix.space_context.ask. It does not explicitly say when not to use this tool, but the intended usage 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?

The description goes well beyond the annotations by disclosing that the operation is irreversible, free, returns { space_id }, and returns 404 for missing or foreign spaces. It also states that no body or query parameters are accepted, giving the agent a complete behavioral picture.

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 brief and front-loaded, with every sentence adding essential information: endpoint, ownership, response, irreversibility, cost, and error behavior. There is no fluff or repetition of schema 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 destructive operation with one required parameter and an output schema, the description covers all critical aspects: what is deleted, who can delete it, what happens on success and failure, and the irreversible consequence. Nothing an agent needs 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?

The input schema already has 100% coverage, including a detailed description of space_id and api_key. The tool description adds route-level context but no new parameter-specific meaning, so the baseline score of 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 states a specific verb and resource: delete a knowledge space, constrained to one owned by the API key. It also includes the exact endpoint, making the tool's function unambiguous. It is clearly distinct from siblings like claix.spaces.create and claix.document.delete.

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 ownership constraint and 404 error condition make it clear which spaces are valid targets. It does not explicitly name alternative tools or say when not to use it, but the tool name and sibling context make the intended scope sufficiently 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?

Beyond the read-only/idempotent annotations, it discloses the exact response fields (user_ask, ia_response, log_id), the null behavior for absent answers, and the permission-dependent shape {value, source} with markdown evidence or requires_human_revision. This gives an agent realistic expectations about outputs without needing to open the 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?

The description is front-loaded with the core action, quickly covers prerequisites and constraints, and then gives return semantics. Despite its length, each sentence carries a distinct fact; no filler or repetition beyond reinforcing schema constraints.

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, idempotent ask tool with an output schema and only 3 parameters, the description covers the prerequisite flow, input limits, response structure, and permission-based variation. Nothing needed to decide or execute a call 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?

The input schema already covers all three parameters and their constraints, so the baseline is 3. The description adds value by specifying where document_id comes from ('from an extraction with window_context') and by restating the 5-question/400-character limits in natural language; however, it does not add much beyond the schema for api_key.

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 specific verb and resource: 'Ask up to 5 questions about a persisted document', reinforced by the POST /document-context/{document_id} endpoint. This clearly separates it from siblings like window_context.get (retrieval) and space_context.ask (space-level asking), even without naming them.

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 a clear precondition: 'Requires document_id from an extraction with window_context', which tells an agent this tool is only meaningful after a window_context extraction has produced an ID. It does not explicitly contrast with space_context.ask or list exclusions, so it stops short of a fully explicit when-to-use/when-not-to-use statement.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: the exact endpoint, the returned fields, and the fact that it is free. There is 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 focused sentences: the action and endpoint, the required input origin, and the return fields plus cost. Every sentence contributes useful information, and the key action 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?

For a simple read-only retrieval, the description covers the endpoint, prerequisite, return fields, and cost. It does not mention error behavior, but the presence of an output schema and the safe annotations mitigate that gap.

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 provides 100% coverage, including descriptions, types, formats, and examples for both api_key and document_id. The tool description mostly repeats the provenance of document_id rather than adding significant new semantics, so the baseline score of 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 ('Retrieve'), names the resource ('persisted document'), and includes the HTTP endpoint (GET /get-document/{document_id}). It also clearly ties the tool to a specific workflow by stating that document_id comes from a window_context extraction, making it easy to distinguish from sibling tools like delete, extract, or ask.

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 clear context: the tool requires a document_id produced by a window_context extraction, and it notes that the call is free. It does not explicitly name alternative sibling tools or say when not to use it, but the prerequisite is strong enough to guide selection.

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