Claix

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

Annotations already declare a safe, idempotent read; the description goes well beyond that with format support (MP3/WAV/M4A/OGG), size/duration limits (12 MB / 10 min), and conditional response shapes tied to schema config (row_id, {value, source}). Return-value detail is somewhat redundant given an output schema 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?

Front-loaded with the core action and the key constraint; sentences are dense but each contributes (formats, limits, conditional returns). No filler, though 'No space_id' and the mixed-language 'Guardar Datos' add minor noise.

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 5-param processing tool with an output schema, the description covers inputs implicitly, formats, limits, and conditional output variants. The main gap is that 'is_agent_mode' is asserted as a requirement without existing in the schema, leaving a small ambiguity.

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 params are already documented, giving a baseline of 3. The description adds no parameter-level detail and even references a non-existent 'is_agent_mode', adding slight confusion rather than 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?

States a specific verb+resource ('Run audio extraction plus Agent mode reasoning'), and the 'plus Agent mode reasoning' phrase distinguishes it from the plain claix.extract.audio sibling. It does not explicitly name the sibling, but the agent-mode qualifier is a clear differentiator.

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 signal is 'Requires is_agent_mode', and is_agent_mode is not even a parameter in the schema, which makes the prerequisite confusing rather than helpful. There is no explicit when-to-use-this vs claix.extract.audio / claix.markdown.audio 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds genuinely useful behavioral context: the response shape (data[], agent_data, log_id), the conditional row_id when Guardar Datos/window_context is present, the explicit 'No space_id', and the {value, source} wrapping when source verification is on. That is meaningful disclosure beyond 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?

Front-loaded with the core purpose, then the output contract and its conditionals; nearly every sentence adds information. It is dense and slightly terse ('No space_id.'), but there is little waste.

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?

An output schema exists, so return values need not be explained, yet the description helpfully flags the conditional row_id and {value, source} shape. Combined with annotations and full schema coverage, an agent has what it needs, though the relationship to sibling extract/markdown tools is left unstated.

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 each parameter is richly documented, so the schema carries parameter semantics. The description adds no per-parameter detail beyond the out-of-schema is_agent_mode flag, so the 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?

States a specific verb+resource ('Run document extraction plus Agent mode reasoning') and enumerates the supported formats (.docx/.txt/.md/.rtf), which implicitly separates it from claix.agent.pdf/excel/audio and from plain claix.extract.doc. It never names a sibling explicitly, so it stops short of full differentiation, but the purpose is 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 usage via 'Agent mode reasoning' and the prerequisite 'Requires is_agent_mode', letting an agent infer this is the agent-enabled variant. However, it never states when to prefer this over claix.extract.doc or claix.markdown.doc, and the referenced is_agent_mode flag does not appear in the schema, leaving the routing implicit.

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, so safety is covered. The description adds genuinely new behavioral detail: conditional output shape when Guardar Datos is present (row_id), the absence of space_id, and the {value, source} wrapping when source verification is enabled.

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 purpose leads, followed by prerequisite, return fields, and conditionals in dense, low-waste sentences. A few terse fragments ('No space_id.') are abrupt but still carry information rather than padding.

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 an output schema present, return values need not be explained, yet the description usefully flags conditional return shapes. It covers prerequisites and schema-driven behavior well; only the mechanics of what agent-mode reasoning actually does remain unspecified.

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 raises it by explaining how schema_id configuration (is_agent_mode, Guardar Datos, source verification) changes tool behavior and output, adding meaning beyond the parameter's own schema description.

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 (extraction) plus resource (Excel/CSV) and a distinguishing capability (Agent mode semantic reasoning), which separates it from the plain claix.extract.excel sibling. However, it never explicitly names an alternative, so the boundary is inferred rather than stated.

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 prerequisite 'Requires is_agent_mode on the schema' implies when this tool is applicable, and the agent-mode framing hints at its use case. But there is no explicit when-to-use/when-not guidance or direct routing to claix.extract.excel or claix.agent.pdf for comparison.

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 (readOnly, idempotent, non-destructive, openWorld), yet the description adds real behavioral detail: return shape (data[], agent_data, log_id), conditional row_id when the schema has Guardar Datos, absence of space_id, and the {value, source} field format under source verification. The 'Requires is_agent_mode' note adds a requirement, though it references a parameter absent from the 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?

Front-loaded with the core purpose and kept to four sentences with no filler. The clipped fragments ('No space_id.') are terse but the overall structure is efficient 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?

For a tool with an output schema and full parameter documentation, the description is nearly sufficient, adding schema-dependent return behavior (Guardar Datos/row_id, source-verification fields) that structured fields cannot express. The reference to a non-schema 'is_agent_mode' requirement is the one loose end.

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 five input parameters are fully documented in the schema and the baseline is 3. The description adds no meaning for any of those parameters and instead introduces 'is_agent_mode,' a flag that does not appear in the input schema, which slightly muddies rather than clarifies 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?

States a concrete verb+resource+mode: 'Run image extraction plus Agent mode reasoning,' which separates it from plain claix.extract.image and claix.markdown.image by the Agent-mode reasoning twist. It does not explicitly name those siblings, so the differentiation is implicit rather than spelled out.

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 an implied usage condition ('Requires is_agent_mode'), which hints this is the agent-augmented variant, but never states when to prefer it over claix.extract.image or the other agent.* image tools. No exclusions, prerequisites, or alternative routing are given.

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 the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds genuine conditional behavior: row_id appears only when the schema has Guardar Datos (window_context), no space_id is returned, and fields become {value, source} when source verification is on. These schema-dependent output behaviors are real added context.

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?

Purpose and the is_agent_mode requirement are front-loaded, and the conditional return behavior is packed into short clauses. Some fragments ('No space_id.') are choppy, but overall it is dense with little wasted text.

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 an output schema, full schema coverage, and annotations present, the description's job is lighter. It covers purpose, key returns, and conditional response shapes adequately, though it omits usage routing versus sibling extraction tools.

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 five parameters, giving a baseline of 3. The description does not add syntax or format detail beyond the schema, and it oddly references 'is_agent_mode' which is not an actual parameter in the schema, which does not help parameter understanding.

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 PDF extraction plus Agent mode reasoning.' The 'plus Agent mode reasoning' clause distinguishes it from the plain claix.extract.pdf sibling, and 'PDF' distinguishes it from the other claix.agent.* media tools. It stops short of naming the alternatives explicitly, so it is clear but not maximally differentiated.

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-oriented statement is 'Requires is_agent_mode,' which reads as a prerequisite rather than when-to-use guidance. There is no indication of when to prefer this over claix.extract.pdf, claix.markdown.pdf, or the other agent.* variants.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond listing the body fields, which merely repeats the schema; it does not disclose auth needs, side effects, or what happens on duplicate slug.

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?

A single front-loaded sentence with the action first and the endpoint/body following. It is tersely structured, though the body enumeration partially duplicates the schema rather than adding 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?

An output schema exists, so return values needn't be explained, and the schema fully documents all parameters. The description covers the create action adequately; its only real gap is the absence of usage guidance, which is minor given the rich structured fields.

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 every parameter including api_key is already documented in the schema. The description recaps six of the seven body fields (omitting api_key) but adds no format or constraint meaning beyond what the schema provides, 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?

States a specific verb (Create) and resource (a Retrieve agent), plus the underlying endpoint POST /agents. This clearly differentiates it from sibling creation tools (routes.create, schemas.create) and from agents.edit/pause.

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 never states when to use this tool versus alternatives such as agents.edit or the other create tools. There is no precondition or exclusion guidance; the agent must infer that 'create' means a new agent is needed.

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=false, idempotentHint=true and destructiveHint=false, so the safety/mutation profile is covered. The description adds the PUT verb and 'same body as create plus agent_id', which usefully signals full-replacement semantics (consistent with 7 required fields), but it does not state what happens to the live agent, auth requirements, or side effects.

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?

One front-loaded sentence plus a short clarifying clause; both carry information and there is no padding. It is arguably terse for a 7-required-parameter mutation tool, which keeps it just short of a 5.

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 an output schema present and 100% schema coverage, return values and parameter details are covered elsewhere, so the description need not repeat them. It correctly identifies the resource and its create-relative shape; only live-effect and auth context are 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 description coverage is 100%, so the schema already documents every parameter and the baseline is 3. 'Same body as create plus agent_id' adds a small amount of meaning by mapping the field set to create, but no syntax or format details beyond the schema are provided.

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 ('Edit a Retrieve agent') and adds the concrete endpoint (PUT /agents/edit/{agent_id}), which lets an agent distinguish it from claix.agents.create and claix.agents.pause. The phrase 'Same body as create plus agent_id' further anchors it against the create sibling, though it never names pause as the alternative.

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?

There is no explicit when-to-use or when-not guidance. The reference to create implies a relationship (edit an existing agent vs. make a new one), but no conditions, prerequisites, or alternative-selection rules are given. The agent must infer usage entirely.

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 the full safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description restates the body shape already present in the schema but adds no behavioral context such as whether pausing interrupts in-flight retrievals, whether an API key is required, or what happens to a paused agent's data.

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 short clauses with zero filler; the action and endpoint are front-loaded and the body shape follows immediately. Nothing in the sentence is redundant padding.

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 state-toggle with full schema coverage and an output schema (so return values need no explanation), the description covers what is needed to invoke it correctly. Only the absence of usage routing to sibling tools keeps it from being fully 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%, so all three parameters (agent_id, status enum, api_key) are already documented in the schema. The description's body notation duplicates the status enum rather than adding syntax or format meaning beyond it, so the 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?

States a specific verb pair (pause/activate) and the exact resource (a Retrieve agent), plus the underlying endpoint POST /agents/pause/{agent_id}. An agent can tell it is a state-toggle operation, though it does not explicitly distinguish itself from claix.agents.edit, the nearest 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?

Usage is implied by the tool's purpose — call it to disable or re-enable an agent — but there is no explicit when-to-use guidance, no prerequisites, and no pointer to alternatives like claix.agents.edit for other agent modifications.

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/openWorld, so the safety profile is covered. The description adds real behavioral context beyond that: the return shape (data[], agent_data, log_id), the conditional row_id when the schema has Guardar Datos (window_context), and the {value, source} field format when source verification is enabled.

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?

Purpose is front-loaded in the first clause and the description is dense and efficient. It is somewhat telegraphic, with fragments like 'No space_id.' that read as terse notes rather than polished guidance, but nothing is wasted.

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?

An output schema exists, so return values need not be explained, yet the description covers return shape, conditional behaviors, and the endpoint (POST /agent/txt-json). The only gap is the dangling 'Requires is_agent_mode' reference, which points at a parameter the agent cannot see in the schema.

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 all three parameters are already documented in the schema. The description reinforces content semantics ('no file') but adds little parameter-level detail beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource: 'Run text/HTML/XML extraction plus Agent mode reasoning.' The content-type qualifier (text/HTML/XML) distinguishes it from the sibling agent.* tools (audio, doc, excel, image, pdf) and from extract.text. However, 'Requires is_agent_mode' references a parameter that does not exist in the schema, which muddies the purpose slightly.

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 usage constraints ('Send content (no file)', 'No space_id') that imply correct invocation, but never names an alternative tool or says when this should be chosen over claix.extract.text or claix.markdown.text. Usage 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 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?

Annotations already declare the safe read profile, yet the description adds substantive operational context well beyond them: input limits (12 MB / 10 minutes), returned log_id, conditional row_id via Guardar Datos, absence of space_id, per-field {value, source} shape under source verification, and HTTP 422 for unintelligible audio. This is exactly the kind of behavioral detail the annotations do not carry.

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 carries distinct information and the purpose is front-loaded before constraints, output fields, error behavior, and use cases. No filler or repetition despite the density.

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 an output schema present and rich annotations, the description supplies the remaining needed context: input limits, error semantics (422), and the conditional output fields (log_id, row_id, {value, source}). An agent has everything required 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 description coverage is 100%, so all five parameters (including api_key, file_path, file_base64) are already documented in the schema. The description only reinforces the audio-json schema_id concept and file formats; it adds no guidance on choosing file_path vs file_base64 or on the api_key fallback, so the 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?

States a specific verb and resource ('Extract structured JSON from spoken audio') with supported formats listed, which clearly separates it from extract.pdf/doc/excel/image/text. However, it does not differentiate itself from the three audio-modality siblings (agent.audio, markdown.audio), so sibling routing is incomplete.

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?

'Use for calls, meetings, voice notes, or dictations' gives clear positive context for when this tool applies. There are no explicit exclusions or named alternatives (e.g., when to prefer markdown.audio or agent.audio), keeping it below 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 readOnly/idempotent/non-destructive, so the bar is lowered, yet the description adds real behavioral context: returns log_id, may include row_id when the schema has Guardar Datos, wraps fields as {value, source} when source verification is on, and enforces a 10 MB limit with legacy .doc unsupported. It stops short of 5 because it doesn't cover failure/error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and format list, then conditional behaviors. Dense but every clause carries information (return fields, size cap, unsupported format). Slightly cluttered by the terse 'No space_id' fragment.

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 an output schema present the description needn't document return values, yet it still explains log_id/row_id/source-wrapping and the size/format constraints. Complete enough for correct invocation; only cross-sibling routing is left unstated.

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 api_key, filename, file_path, schema_id and file_base64 in detail; the description adds only tangential parameter context ('No space_id', schema requirements). Baseline 3 is appropriate when the schema does the heavy lifting.

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+resource (extract structured JSON from a Word document) and enumerates the accepted formats (.docx, .txt, .md, .rtf) plus the 10 MB cap, which separates it from the pdf/excel/image/audio extract siblings. It does not explicitly distinguish itself from claix.extract.text, which overlaps on .txt/.md, so it falls just short of a 5.

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?

Usage is implied via 'using a Claix doc-json schema' and the '.doc not supported' exclusion, and it notes the required schema_id indirectly in the schema. However it never says when to prefer this tool over claix.extract.text or claix.agent.doc, nor does it state prerequisites such as obtaining schema_id first (that guidance lives in the parameter 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?

Goes well beyond the readOnly/idempotent annotations: first-sheet-only processing, returned log_id, conditional row_id when the schema carries Guardar Datos (window_context), absence of space_id, and the field-shape change to {value, source} under source verification. These are exactly the non-obvious behaviors 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 purpose, then layers schema-dependent behavior, ending with the usage trigger. Dense and mostly waste-free, though the clause stack ('If... If...') makes it slightly harder to scan than it needs to be.

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?

An output schema exists so return values need not be explained, and the one required parameter (schema_id) is covered by the schema. The description supplies exactly the missing behavioral context: sheet scope, return extras, and conditional field 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?

Schema description coverage is 100%, so the schema already documents all five parameters (api_key, filename, file_path, schema_id, file_base64). The description adds no per-parameter meaning beyond the incidental 'No space_id' remark, 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?

States a precise verb+resource+format: 'Extract structured JSON from an Excel (.xlsx) or CSV file using a Claix excel-json schema.' This distinguishes it cleanly from sibling extractors (pdf, doc, image, audio) even though they are not named.

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?

'Use when the user attaches a spreadsheet or CSV' gives a clear triggering condition. It does not name an explicit alternative or a when-not case (e.g. when to prefer claix.agent.excel or claix.markdown.excel), so it falls 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 readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description goes further by disclosing output behavior not in the annotations: returns log_id, may return row_id only when the schema has Guardar Datos, no space_id, and that source verification changes each field to {value, source}. The telegraphic 'No space_id' is unclear but the rest is genuinely additive.

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-loaded with purpose and format/size limits, then output shape and use case; nearly every clause carries information. The fragment 'No space_id.' is terse to the point of ambiguity and is the one sentence that does not clearly earn 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?

Covers input formats, size limit, how to obtain schema_id (via claix.schemas.list, per the schema), use case, and the conditional output fields. With an output schema present, return-value detail is technically redundant but harmless; auth via header vs api_key is left entirely to the schema.

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 constraints the schema does not state: the accepted image MIME types and the 15 MB maximum, plus the requirement that schema_id refer to a Claix img-json schema. Those qualify the file and schema parameters in ways an agent cannot read off 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 specific verb and resource ('Extract structured JSON from a visible image') and scopes it with accepted formats (JPEG, PNG, WebP, HEIC/HEIF) and a size ceiling, which distinguishes it from the pdf/doc/text extractors. It never names a sibling, so disambiguation from claix.agent.image or claix.markdown.image is left to inference.

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?

'Use for photos of documents, tickets, or labels' gives a positive use context, but there is no when-not guidance and no routing among the many near-identical siblings (extract.pdf, extract.doc, markdown.image, agent.image). In a ~30-tool family, context without exclusion is only implied 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 readOnly/idempotent/non-destructive, but the description adds real behavioral context: 15 MB size cap, acceptance of text or scanned PDFs, and conditional output shaping (row_id with Guardar Datos, {value, source} with source verification, no space_id). Some of this return detail is redundant given the output schema 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 core action and size limit are front-loaded, and each sentence carries information (constraints, return shape, use cases). It is slightly dense with schema-specific jargon but not padded.

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 extraction tool with 100% schema coverage and an output schema, the description supplies the missing context an agent needs: size limit, input types, and conditional return fields. Nothing critical is omitted.

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 five parameters (including schema_id, file_path, file_base64) are already documented. The description adds no parameter-level meaning beyond output notes, so the 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?

States a specific verb (Extract), resource (PDF), and output (structured JSON), making it easy to separate from claix.extract.text/excel or claix.markdown.pdf. It does not explicitly name the nearest sibling (e.g., extract vs markdown for PDFs), so differentiation is implied rather than stated.

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?

"Use for invoices, contracts, forms, or reports" gives clear context for when this tool applies. However, it offers no exclusions or routing guidance to alternatives like claix.markdown.pdf or claix.agent.pdf.

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 the safe read-only, idempotent profile, and the description adds real behavioral context beyond them: a 300,000-character limit, the returned log_id, conditional row_id when Guardar Datos is set, and the {value, source} shape under source verification. It is rich and specific, though it does not fully explain failure/error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then terse supporting facts. Some fragments like 'No space_id.' and 'Returns log_id.' are choppy but each sentence carries a distinct, useful constraint.

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?

An output schema exists so return values need not be spelled out, yet the description still explains the log_id/row_id response behavior and the source-verification field format. Combined with the payload and size constraints, an agent has what it needs to call this 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 description coverage is 100%, so the schema already documents api_key, content, and schema_id, giving a baseline of 3. The description reinforces that payloads go in 'content' and adds the 300,000-char ceiling not present in the schema, but this is a marginal addition over the structured fields.

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) and resource (structured JSON from plain text/HTML/XML), and the txt-json schema mechanism. It implicitly distinguishes itself from the file-based siblings (extract.pdf, extract.doc, etc.) by naming text/HTML/XML as the input, though it never names a sibling 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 'already processed' phrasing plus 'no file' clearly establishes that raw documents should not be sent here, which is a meaningful routing condition versus the file-oriented extract.* tools. It stops short of naming an alternative tool or stating explicit when-not cases, so it is not 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?

The description states that save=true 'inserts into the connected DB' and 'may return row_id' — a state-mutating path — while the annotations declare readOnlyHint=true and idempotentHint=true. That is a direct conflict: an insert is neither read-only nor idempotent. Per the rubric this is an Annotation Contradiction, so the score is 1 even though the write-path detail is itself informative.

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 clauses, front-loaded with purpose, endpoint and the save behavior. Slightly telegraphic ('No schema_id'), but every clause carries signal and there is no 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?

An output schema exists, so return shapes need not be spelled out, and the description covers the endpoint and the two save outcomes. Only the read-only-vs-write inconsistency with the annotations leaves an agent without a coherent behavioral model.

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 save, api_key, filename, file_path and file_base64. The description restates the save semantics and adds the 'No schema_id' constraint, but contributes no syntax or format detail beyond the schema. 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?

States a specific verb+resource ('Convert spoken audio to Markdown') plus the backing endpoint, so the agent can tell it apart from the sibling markdown.doc/pdf/image/text converters and from claix.extract.audio. The 'No schema_id' note further narrows its contract.

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?

Explains the save=true vs omit/false branch, which is real usage guidance for one parameter, but says nothing about when to pick this tool over siblings like claix.extract.audio or claix.agent.audio. Context is implied rather than explicit.

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 description states save=true 'inserts into the connected DB', which is a state-changing write. That directly contradicts the read-only annotation (and the idempotent/no-destructive framing), so the description undermines rather than reinforces the structured safety signals.

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 core conversion purpose, then the endpoint, then the save branch. Efficient and free of padding, though the 'No schema_id' fragment is terse and slightly cryptic out of context.

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?

An output schema exists, so return values needn't be explained, and the description covers the endpoint and the one behaviorally significant branch (save). The main gap is the unaddressed conflict between the write-on-save behavior and the declared read-only annotations.

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 all five parameters are already documented in the schema, including save. The description restates the save semantics and adds nothing new for filename, file_path, file_base64, or api_key, 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?

States a specific verb (Convert) and resource (Word/text document) with an explicit output (Markdown), and the '.doc' scope distinguishes it from siblings like claix.markdown.pdf, claix.markdown.text, and claix.markdown.excel. The endpoint reference and 'No schema_id' note further pin it down.

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 clarifies the save=true vs omit/false behavior, which is real usage guidance for that parameter. However, it never says when to choose this over claix.markdown.text or claix.agent.doc, so tool-selection guidance is only implied by the document-type scope.

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 annotations declare readOnlyHint=true, but the description states that save=true inserts into the connected DB using Markdown rules and may return a row_id — a mutation side effect. A tool that can write to a database cannot truthfully be advertised as read-only, so the description directly contradicts the annotation.

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/three compact sentences with the primary purpose front-loaded, endpoint in parentheses, then the save branching. Efficient and scannable, with little wasted text.

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?

An output schema exists, so return values need not be re-explained, and the save/return-only behavior is covered. However, the annotation contradiction leaves the side-effect profile ambiguous, and the file-source parameters are left entirely to the schema.

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 every parameter (save, api_key, filename, file_path, file_base64) is already documented in the schema. The description only restates the save semantics and adds a 'No schema_id' note, adding marginal value beyond the schema 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?

States a specific verb+resource ('Convert Excel/CSV to Markdown') and even names the backing endpoint (POST /api/excel-markdown). The format (Excel/CSV) implicitly distinguishes it within the claix.markdown.* family (audio/doc/image/pdf/text), though it never explicitly names a 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 'No schema_id' note and the save-vs-return-only branching imply when to use each mode, but there is no explicit guidance on how this differs from claix.agent.excel or claix.convert.json_to_excel, nor on prerequisites or file-source 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?

The description is genuinely transparent about the optional write path ('save=true inserts into the connected DB... may return row_id'), which the annotations do not capture. However, this disclosed DB insert directly conflicts with the declared readOnlyHint=true, so the description and annotations are inconsistent; the transparency is real but the conflict prevents a higher score.

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, front-loaded with the action and endpoint, with no filler. It is dense with parenthetical detail but every clause (endpoint, no schema_id, save semantics) carries information an agent needs.

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?

An output schema exists and all inputs are schema-documented, so return values and input formats need not be restated. The description covers the endpoint, the optional persistence path, and the absence of schema_id, leaving it essentially complete for a low-complexity conversion tool, though the readOnlyHint conflict slightly undercuts it.

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 all five parameters are documented in-schema, so the baseline is 3. The description echoes the save semantics already in the schema and adds the 'No schema_id' clarification, but contributes no syntax or format detail beyond the structured fields.

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+resource ('Convert image to Markdown') and even names the backing endpoint (POST /api/img-markdown), so the agent knows exactly what it does. It is distinguishable from siblings via 'image' in the name/title, but the description itself never differentiates it from claix.markdown.pdf/.doc/.audio or claix.extract.image, so it stops short of a 5.

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 'No schema_id' note is a weak differentiator versus schema-driven siblings, and the save=true/false semantics describe behavior rather than when to pick this tool. There is no explicit 'use this instead of X when Y' guidance, so an agent must infer routing from the tool name alone.

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 says save=true 'inserts into the connected DB', a write operation, while annotations declare readOnlyHint=true. This directly contradicts the structured safety metadata instead of reconciling 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?

Compact and front-loaded: conversion purpose first, then the key save flag and DB behavior. The 'No schema_id' note is a useful fragment rather than wasted prose.

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 a full input schema and an output schema, the description need not explain parameters or return values, and it does cover the optional save/row_id outcome. However, it fails to reconcile that write behavior with the readOnly annotation, leaving a potentially misleading context for the agent.

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 five parameters are already documented in the input schema. The description repeats the save behavior but adds no parameter meaning 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 and resource: 'Convert PDF to Markdown'. The name, title, and endpoint make it distinguishable from sibling extraction and other markdown conversion tools without needing to open the 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?

Clarifies the save=true vs omit/false behavior and notes 'No schema_id', which gives some usage context. It does not compare against alternatives like extract.pdf or agent.pdf, so the agent receives no explicit when-to-use 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?

The description usefully discloses the write path (save=true inserts into the connected DB and may return row_id; omit/false returns markdown only), which is valuable behavioral context. But this write capability conflicts with the declared readOnlyHint=true, since save=true modifies the DB environment. The description is transparent about the conflict, so it is a conditional rather than flat contradiction, warranting 2 rather than 1.

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 purpose is front-loaded, followed by input constraints and then the save/return behavior, all within three terse clauses. Every element carries information and there is no padding, though the endpoint parenthetical is slightly incidental.

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 an output schema present, return values need not be explained, and the description covers source types, the in-memory input requirement, and the save behavior. What is missing is an explicit pairing with sibling conversion tools and a caveat about the read-only annotation being inapplicable when save=true.

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 both 'content' and 'save' are already documented in the schema, and the description largely restates them. It adds minor clarification ('no file, no schema_id' for content, row_id return for save), but the schema does the heavy lifting, so the 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 states a concrete verb and resource ('Convert plain text/HTML/XML to Markdown') and even gives the backing endpoint POST /api/txt-markdown, making the tool immediately identifiable. It implicitly separates itself from file-based siblings (markdown.pdf/doc/image) by 'no file, no schema_id', though it does not explicitly name those alternatives.

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?

'content field, no file, no schema_id' conveys the in-memory string variant and steers the agent away from file/schema-based siblings, so the usage context is implied. However, it never explicitly frames when to prefer this tool over claix.agent.text, claix.extract.text, or the other claix.markdown.* 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds real operational context (multipart with repeated 'file' field, questions as a JSON string), but its return-value listing (user_ask, ia_response, documents_processed, log_id) largely duplicates the output schema, and it does not note that window_context=true may cause documents to be retained beyond the call.

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 purpose is front-loaded in the first clause, followed by mechanics in a compact paragraph. The endpoint reference (POST /multi-document) and the return-field list are lower-value additions that could be trimmed, but overall it is tight and readable.

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 fairly complex tool (6 params, nested question objects, multipart upload) with a 100% covered schema, annotations, and an output schema, the description supplies the missing glue: multipart shape, per-call limits, and the typed-question structure. It does not explain the retention semantics of window_context or the api_key fallback, which are left to the schema.

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 every parameter is already documented in the schema, including the format enum and the window_context/window_time relationship. The description only restates the format enum and gestures at the optional parameters matching OpenAPI MultiDocumentRequest, adding no syntax or constraint detail beyond the schema. 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 gives a concrete verb (ask typed questions) and resource (multiple uploaded documents), and states the operational envelope (up to 5 questions, up to 10 documents). This implicitly separates it from single-document siblings like claix.retrieve.ask and the extract.* family, but it never explicitly names an alternative, so it falls short of a 5.

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 scope limits (max 5 questions, max 10 documents) imply when the tool applies, but there is no explicit when-to-use guidance, no prerequisites, and no routing to sibling tools such as claix.retrieve.ask or claix.agent.* for single-document or single-question cases. Usage is inferable but not 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered structurally. The description adds the request shape and the razonada-conditional format rule, which is useful, but says nothing about latency, cost, or the non-determinism an LLM-backed 'razonada' agent implies despite the idempotentHint=true annotation. No contradiction, but limited added behavioral context.

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 endpoint and body shape in a few dense sentences with no filler. It loses a point for duplicating the format enum and conditional rule that the schema already states, which is wasted space rather than new 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?

An output schema exists, so return values need not be explained, and the description covers endpoint, body, the conditional format rule, and agent_name resolution. The only real gap is the absence of any routing guidance against the closely related multi_document.ask sibling.

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 largely restates what the schema already documents — the format enum list and the 'required only for razonada agents' rule appear verbatim in both places — and adds no syntax, naming, or slug-resolution detail beyond it.

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?

Names a specific verb+resource ('Ask a Retrieve agent') and pins it to the POST /retrieve/{agent_name} endpoint, so the action is unambiguous. It does not distinguish itself from the sibling claix.multi_document.ask, which also asks questions, so an agent cannot route between the two from the text alone.

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?

Usage is only implied ('ask a Retrieve agent'), with one conditional rule carried over from the schema (format required only for razonada agents). There is no statement of when to pick this over multi_document.ask or any other extract/ask sibling, and no prerequisites beyond the api_key note that lives in the schema.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the write/non-idempotent profile is covered structurally. The description adds the endpoint verb (POST /routes), which is useful context, but says nothing about side effects, permission requirements, or what state a new route starts in.

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?

A single tight sentence with the action and endpoint front-loaded and zero filler. The inline body recap is mildly redundant against a fully documented schema, but it costs little and stays compact.

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?

An output schema and annotations exist, so return values and the safety profile need not be explained. However, for a creation tool whose inputs depend on a published Data Map, the absence of any prerequisite or failure-mode context leaves a 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?

Schema description coverage is 100%, so all five parameters are already documented in the schema; the description merely restates the body shape (name, description, rules, tables[].name, tables[].columns). It adds no semantics beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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 ('Create') and resource ('Retrieve route'), plus the HTTP endpoint POST /routes, so the agent can distinguish it from claix.routes.edit and claix.routes.delete. It does not explicitly name siblings or contrast them, but the verb/resource pair is 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?

No indication of when to create a route versus editing an existing one, nor any prerequisites (e.g. that tables must come from a published Data Map). The body shape hints at required inputs but gives no usage context or exclusions.

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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the HTTP method and path, but says nothing beyond annotations about reversibility, auth requirements, or side effects.

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?

A single compact sentence with the action and endpoint front-loaded; nothing is redundant or buried. Very tight, though it could carry slightly more useful detail without bloat.

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?

An output schema exists so return values need not be explained, and annotations cover the destructive/idempotent behavior. For a simple two-parameter delete tool the description is nearly complete, missing only usage context and confirmation of what gets removed.

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 both api_key and route_id are already documented in the schema. The description's 'Requires route_id' merely restates the required field and adds no format or interpretation detail beyond the schema. 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?

States a specific verb+resource ('Delete a Retrieve route') and even gives the underlying endpoint (POST /routes/delete/{route_id}), so it is clearly distinguished from claix.routes.create/edit and claix.schemas.delete. It stops short of explicitly contrasting with any sibling, which keeps it just under a 5.

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 says only 'Requires route_id' and gives no when-to-use/when-not guidance, no prerequisites, and no reference to alternatives like claix.routes.edit. Usage is only weakly implied by the verb 'Delete'.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The 'same body as create' phrasing does hint that this is a full replacement rather than a partial patch, which is genuinely useful PUT semantics. Still missing are any notes on required permissions, what happens to fields omitted from the body, or whether concurrent edits are a concern.

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 short sentences with zero filler. The endpoint and the body-source reference are front-loaded, so an agent gets the essential facts in the first read.

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 an output schema present, return values need no explanation, and the 100%-covered input schema documents all six parameters. The description covers the operation and body shape adequately for a mutation tool, though it leaves the agent to infer that sibling create's body is authoritative and that api_key is optional when the MCP header carries it.

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 every parameter is already documented in the schema, which sets the baseline at 3. The description adds only one small clarification — that route_id is a path param rather than a body field — and defers the rest of the parameter meaning to the create tool's 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?

States a specific verb and resource ('Edit a Retrieve route') and ties it to a concrete endpoint (PUT /routes/edit/{route_id}), which cleanly separates it from claix.routes.create and claix.routes.delete. It does not explicitly say what distinguishes an edit from a create beyond the presence of route_id, but the verb+resource pairing is 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 clause 'Same body as create plus route_id path param' implicitly tells the agent when to reach for the create schema as a reference, which is helpful. However, there is no explicit when-to-use vs. when-not-to-use guidance, no statement of prerequisites (e.g. the route must already exist), and no mention of the delete sibling as the alternative for removal.

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 the safety profile (not read-only, open-world, not idempotent, not destructive), so the bar is lower. The description still adds real behavioral context: the window_context flag causes JSON extractions to insert a mapped row into the connected DB and requires a connection plus mapping rules, which is an important side effect an agent would not otherwise know.

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-loaded with verb, resource, and endpoint, then requirements, then optionals. It is dense but every clause carries information; only minor duplication with the schema descriptions keeps it from a 5.

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 9-parameter mutation tool with a nested agent_definition/schema_definition and an output schema, the description covers the required fields, the meaningful optionals, and the window_context side effect. Return values are rightly omitted since an output schema exists; auth (api_key) is left to the schema but is optional here.

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 nine parameters in detail, including window_context and cita_por_campo. The description largely restates required/optional fields and the enum values rather than adding syntax or format meaning beyond the schema, matching the baseline of 3.

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 (Create) and resource (Claix schema) and even names the underlying endpoint (POST /api/create-schema). This cleanly separates it from the other schemas.* siblings (get/list/update/delete) via the verb, though it never explicitly names those alternatives.

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 lists required vs optional parameters and explains the semantics of window_context, but it gives no explicit when-to-use guidance, prerequisites, or exclusions (e.g. when to prefer create over update). Usage is only implied by the verb.

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 cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower, and the description still adds real behavioral value: it enumerates the returned schema contents, states the call is free, and specifies the 404 semantics including the ownership/API-key scoping rule. It does not discuss auth failures or rate limits beyond that.

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-loaded with the verb, resource and endpoint, followed by return contents and the 404 caveat. No filler; every clause 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?

For a read-one-by-id tool with an output schema (so return values need no elaboration), full annotation coverage, and 100% parameter documentation, the description supplies everything an agent needs: what it fetches, how it is keyed, that it is free, and the failure mode.

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 both parameters (api_key, schema_id) are already fully documented in the schema, which sets the baseline at 3. The description restates schema_id's role and the 404/ownership implication but adds no syntax or format detail 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?

Specific verb (Get) plus resource (one Claix schema) and the keying parameter (schema_id), reinforced by the concrete endpoint GET /api/get-schema/{schema_id}. An agent can trivially distinguish this from claix.schemas.list, create, update, and 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?

Usage is implied (fetch a single known schema by id) and the 404-when-not-owned condition gives useful context, but the description never states when to prefer this over claix.schemas.list — that routing hint ('llama a claix.schemas.list primero si no lo conoces') lives in the schema, not the description. No explicit alternatives or exclusions are provided in the description text.

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 declare idempotentHint=true, destructiveHint=false, readOnlyHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds genuinely new context beyond those: full-configuration replacement semantics, an optional API key path (x-api-key header), and the 'Free call' cost signal. There is a mild tension between 'Replaces the full configuration' and destructiveHint=false, but that is consistent with PUT-style idempotent overwrite rather than a true annotation 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?

Two dense sentences, front-loaded with the action and endpoint, then the required/optional body and replacement caveat. No filler or repetition 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?

The tool ships an output schema, so return values need not be explained, and annotations cover the safety profile. The description supplies the remaining agent-critical facts: full replacement semantics, the HTTP path, API-key optionality, and the free-call cost signal.

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 including enums, defaults, and the Agent-mode/json-excel constraint. The description's parameter list (name, type, schema_definition as required; Agent mode, window_context, source verification as optional) merely restates the schema, adding no format or syntax detail, 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?

States a specific verb+resource ('Update a Claix schema') and pins it to the concrete endpoint (PUT /api/update-schema/{schema_id}), which cleanly separates it from claix.schemas.create/delete/get/list. It does not explicitly name those siblings, but the verb and endpoint leave no ambiguity about what the 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?

'Same body as create' and 'Replaces the full configuration' imply how and when to call it (full replacement rather than a partial patch), which is meaningful guidance. However, there is no explicit when-to-use versus claix.schemas.create or delete, and no stated prerequisites beyond the replacement note.

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