Claix

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

Beyond the annotations (readOnly/openWorld/idempotent), the description discloses return shape (data[], agent_data, log_id), the conditional {value, source} structure when source verification is on, accepted formats, and hard limits (12 MB / 10 minutes). That is genuinely useful behavioral context, though it leaves the is_agent_mode requirement unresolved.

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, and the following sentences each carry distinct, useful facts (returns, formats, limits). The 'Requires is_agent_mode' sentence is the one piece that does not clearly earn its place given no such parameter exists.

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 the return-value explanation is safe to be brief, and the description covers formats, limits, and the source-verification variant. The main gap is the dangling is_agent_mode requirement and the absence of sibling routing guidance.

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 six parameters are already documented and the baseline is 3. The description adds non-parameter constraints (formats, size/duration limits) but also references 'is_agent_mode', which is absent from the schema, creating ambiguity rather than added precision.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a concrete verb+resource ("Run audio extraction plus Agent mode reasoning") and names the output, clearly distinguishing this from the plain extraction sibling. It does not, however, name claix.extract.audio explicitly, so the routing differentiator is implied by 'Agent mode reasoning' 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?

Usage is implied (audio input where agent-mode reasoning is wanted) but never stated as when-to-use vs. claix.extract.audio or the other claix.agent.* tools. The mention 'Requires is_agent_mode' hints at a precondition, but that parameter does not exist in the schema, which muddies rather than clarifies when the tool applies.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the return shape (data[], agent_data, log_id) and the source-verification field format, which is useful, but discloses no auth/permission or failure behavior beyond that. Adequate but not rich.

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, front-loaded sentences with no filler; formats, the mode prerequisite, and the return shape are stated compactly. Slight deduction for the stray is_agent_mode reference, which is not actionable against the schema.

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, the description need not restate return values, yet it summarizes them anyway. It covers formats and mode clearly; the only notable gap is the unexplained is_agent_mode requirement that the agent cannot map to any input.

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 documents all six parameters and the baseline is 3. The description adds no parameter syntax or format detail beyond what the schema provides, and its 'Requires is_agent_mode' reference points at a parameter that does not exist in the schema, which adds ambiguity rather than clarity.

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 separates it from the file-type siblings like claix.agent.pdf and claix.extract.doc. It does not explicitly name a sibling to contrast against, and the phrase 'Requires is_agent_mode' is confusing since no such parameter exists in 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?

The format list implicitly tells the agent this is the .docx/.txt/.md/.rtf Agent-mode path, but there is no explicit when-to-use guidance versus claix.extract.doc (plain extraction) or the other claix.agent.* tools, and no stated exclusions. Usage must be inferred from the file-extension mention.

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 context beyond that: the return shape (data[], agent_data, log_id) and the conditional {value, source} wrapping when source verification is enabled, which is behavioral disclosure not available in 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 tight sentences with the purpose front-loaded and zero filler. Some overlap with the output schema in listing return fields, but overall efficient.

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?

Preconditions (is_agent_mode, source verification) and return-shape behavior are covered, and an output schema plus rich parameter descriptions handle the rest. Adequate for a 6-param, 1-required tool, though it never states the input-source selection logic (file_path vs file_base64).

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 six parameters with examples. The description adds no parameter-level syntax or constraints, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run Excel/CSV extraction plus Agent mode semantic reasoning'), and the 'Agent mode' qualifier distinguishes it from the sibling claix.extract.excel. It does not name the sibling explicitly, so sibling 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?

Provides the key precondition ('Requires is_agent_mode on the schema') but never states when to choose this over claix.extract.excel. Usage is implied by the agent-mode requirement rather than spelled out as when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is light. The description adds useful behavior (returns data[], agent_data, log_id; source verification changes field shape to {value, source}), which is real context beyond the annotations, but it omits auth/permission 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?

Three tight sentences, each load-bearing: capability, gating requirement, and return shape. Front-loaded with the core action and 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?

With an output schema present, the description needn't detail returns, but it does usefully note the {value, source} variant under source verification. The remaining gap is the lack of explicit guidance on when to prefer this over claix.extract.image.

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. The description only restates the is_agent_mode gating condition and does not add syntax or parameter-level meaning beyond the schema, 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 (extraction + Agent mode reasoning) and resource (image), and distinguishes agent mode from plain extraction via 'Requires is_agent_mode'. It is clear against sibling claix.extract.image, though it never outright names the non-agent 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?

The phrase 'Requires is_agent_mode' implies this tool is gated on an external setting before use, but it gives no explicit when-to-use vs. claix.extract.image or the other claix.agent.* siblings, and no 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds useful behavioral detail about return fields and the conditional {value, source} shape when source verification is enabled, but the 'is_agent_mode' requirement references something absent from the schema, creating ambiguity about what the tool actually 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?

Four short sentences, each carrying content, with the core action front-loaded. No filler or repetition; the only blemish is the unexplained is_agent_mode clause.

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 summarizes data[], agent_data and log_id, and it notes the source-verification variant. Combined with annotations covering safety, an agent has enough to call it, though the dangling is_agent_mode requirement 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 the six parameters are already documented in the schema and the baseline is 3. The description adds no syntax or format meaning beyond the schema, and its only parameter-like reference (is_agent_mode) does not exist among the properties.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource ('PDF extraction') and qualifies it with 'Agent mode reasoning', which distinguishes it from the plain claix.extract.pdf sibling in the list. It stops short of explicitly naming the sibling it contrasted against, so it is clear but not fully self-differentiating.

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 statement of when to use this over claix.agent.doc/excel/text or claix.extract.pdf. The only routing hint is 'Requires is_agent_mode', which is not a parameter in the schema, so it gives the agent a false precondition rather than actionable 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 readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower, yet the description still adds return shape (data[], agent_data, log_id), the endpoint, and the {value, source} field format when source verification is enabled. The 'Requires is_agent_mode' claim conflicts with the schema's absence of that parameter, which slightly muddies the behavioral picture.

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

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

Four short, front-loaded sentences with no filler; purpose, prerequisite, input, and return shape are stated in order. Slight deduction because the unexplained 'is_agent_mode' clause consumes a sentence without actionable meaning.

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 enumerated, yet the description helpfully summarizes them. All mandatory concepts (content-based input, endpoint, agent-mode dependency) are present; the only hole is the dangling is_agent_mode requirement.

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, space_id, and schema_id thoroughly. The description only reinforces 'content, not a file' and says nothing about the space_id/schema_id relationship, so it sits at the baseline rather than adding parameter-level 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 concrete verb+resource: text/HTML/XML extraction combined with Agent mode reasoning, and pins it to POST /agent/txt-json. The 'Send content (no file)' phrasing implicitly separates it from the file-based agent siblings (agent.pdf, agent.doc, agent.excel), though it does not explicitly name claix.extract.text as the non-agent 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?

Gives one real constraint ('Send content (no file)') and asserts 'Requires is_agent_mode', which is a usage condition. However, no is_agent_mode parameter exists in the schema, so the guidance is either a hidden server-side requirement or stale text, and the description never says when to prefer this over claix.extract.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 cover safety (readOnly, idempotent, non-destructive). The description adds behavioral context: it requires a schema_id (dependency) and returns base64-encoded xlsx. It also clarifies the file_base64 input should be a .json file, which the schema description ambiguously refers to as PDF/image. No contradiction with annotations.

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

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

Three concise sentences: purpose, input method, and return format. Front-loaded with the primary action, no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-param tool with an output schema, the description covers the core workflow (convert JSON to Excel), input options, and output. It doesn't explain the schema concept in depth, but that is referenced and the schema_id is documented in the schema. Given output schema exists, return values are sufficiently covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, giving a baseline of 3. The description adds meaning by explicitly stating json_data and file_base64 are alternative inputs ('or'), and clarifies that file_base64 should be a .json file, which is not clear from the schema description. This goes beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool converts JSON to an Excel .xlsx file using a Claix schema, with a specific verb and resource. It distinguishes from sibling extract/agent tools by focusing on JSON-to-Excel conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

Beyond the annotations, the description adds 'Irreversible,' 'Free call,' the success response shape, and specific 404 conditions, all of which materially inform an agent's decision to invoke this destructive tool. It fully aligns with the destructiveHint and idempotentHint annotations.

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

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

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter destructive tool, the description covers invocation, success behavior, failure conditions, cost, and side effects. The output schema and parameter descriptions in the input schema cover the remaining structured details, making this definition effectively complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% description coverage, so the baseline is 3. The description adds extra semantic value by clarifying that document_id is a path parameter and that no body or query parameters are accepted, which is not evident from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Delete a persisted document by document_id,' and reinforces it with the exact HTTP path (DELETE /delete-document/{document_id}). This clearly distinguishes the tool from siblings like claix.schemas.delete by targeting persisted documents rather than schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

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

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

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

With annotations already flagging destructiveHint=true and idempotentHint=false, the description still adds substantive behavior: the source document is deleted after a successful copy, a swap is recorded, the version is bumped, and the call is free. This tells the agent exactly what is irreversibly lost.

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 tightly packed sentences with the endpoint, the argument roles, the side effects, and the return values front-loaded. 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?

For a destructive two-argument mutation, the description covers inputs, side effects, versioning, and return fields, and an output schema exists to carry the response shape. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both required UUIDs are already documented in the schema. The description's notes ('kept' vs 'source, deleted after copy') reinforce role semantics but add little that the schema does not already carry; 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 ('Replace the content of a persisted document with another document's content') and pins the HTTP endpoint. An agent can distinguish it from siblings like claix.document.delete or claix.spaces.remove_document without opening 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?

The description explains the mechanics of the swap but never states when to choose this over alternatives or what prerequisites/context it requires. Usage is implied by the operation rather than guided.

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 safety profile is covered. The description adds genuinely useful behavior beyond them: 12 MB / 10 minute ceilings, the log_id return, per-field {value, source} shape under source verification, and HTTP 422 for unintelligible audio. It does not cover auth expectations or how to retrieve results after log_id.

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?

Roughly four dense sentences, front-loaded with verb+resource and then limits, return shape, error case, and usage. No sentence is filler; each adds a constraint or a routing cue.

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 still surfaces log_id and the source-verification field shape. Formats, limits, error behavior, and usage contexts are all covered; the missing piece is differentiation from claix.agent.audio and any async/retrieval guidance.

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 still adds meaning the schema lacks for the file inputs: the accepted audio MIME types and the max size/duration constraints, which directly govern what can legally be passed.

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 spoken audio') and immediately constrains it with accepted formats and size/duration limits. An agent can distinguish it from claix.extract.pdf or claix.extract.image from the name and description 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?

'Use for calls, meetings, voice notes, or dictations' gives clear positive context for when to reach for this tool. However, it never names an alternative or an exclusion, and the very close sibling claix.agent.audio is left un-differentiated, which is the main routing risk.

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 behavior, yet the description adds real value: the 10 MB limit, the returned log_id, and the source-verification mode that changes each field to {value, source}. These are behavioral details the annotations do not convey.

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 dense sentences with the resource and format constraints front-loaded, then the return value, then the exclusion. No filler and 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?

With an output schema present, the description need not explain return shape, and it still covers supported formats, size limits, the log_id return, source-verification semantics and the legacy .doc exclusion. It does not discuss how the file is supplied (file_path vs file_base64), but the schema handles that.

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 every parameter (api_key, filename, space_id, file_path, schema_id, file_base64) is documented in the schema itself. The description only loosely ties to schema_id via 'using a Claix doc-json schema' and adds near-nothing beyond the structured fields, 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 gives a specific verb (Extract) and resource (structured JSON from a document) with supported extensions and a size cap, which meaningfully distinguishes it from extract.pdf. However, it calls the target a 'Word document' while listing .txt, .md and .rtf, and it does not clearly separate itself from the overlapping claix.extract.text 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?

There is no explicit when-to-use guidance or naming of alternatives among the many extract.* and agent.* siblings. The only restriction offered ('Legacy .doc is not supported') is a format limitation, not a condition for choosing this tool over another.

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 burden is lower, and the description still adds real behavior: only the first sheet is processed, a log_id is returned, and fields become {value, source} when source verification is enabled. The one notable gap is how the input file is supplied (file_path vs file_base64 vs filename), which the description leaves to 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?

Four tightly packed sentences, front-loaded with the core verb+source format, then constraints (first sheet), then return shape, then the trigger. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be explained, yet the description still usefully summarizes the JSON+log_id and {value, source} shapes. Combined with the first-sheet constraint and the attach-trigger, it's nearly complete; the only missing piece is a hint about which input parameter to use for the file.

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 six parameters in detail, making the baseline 3 appropriate. The description adds only the notion of a 'Claix excel-json schema' behind schema_id and nothing about file_path/file_base64 usage that isn't already in the schema. Note the schema examples reference PDFs on a spreadsheet tool, but that is a schema-side issue, not a description one.

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 an Excel (.xlsx) or CSV file') and ties it to a Claix excel-json schema, which cleanly separates it from claix.extract.pdf / claix.extract.doc and from claix.agent.excel. The scope (first sheet only) is also stated, so an agent can identify it without opening 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?

Provides a clear trigger: 'Use when the user attaches a spreadsheet or CSV.' However, it never names the sibling alternative (e.g., claix.agent.excel vs claix.extract.excel) or states when NOT to use it, so routing among the many claix.agent.* and claix.extract.* tools is left partly to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the return of a log_id and the fact that source verification changes each field into {value, source}.

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 tight sentences, front-loaded with the core action and formats, then the response shape, then the routing hint. 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 values need not be detailed, yet the description still notes log_id and the source-verification shape. Formats, size limit, and schema dependency are all covered, leaving nothing essential missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters in detail. The description adds only the 15 MB limit, which is not in the schema, leaving the baseline 3 appropriate when the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Extract structured JSON from a visible image') and pins down accepted formats (JPEG, PNG, WebP, HEIC/HEIF) and a size cap. It is clearly distinguishable from siblings like claix.extract.pdf, claix.extract.doc, and claix.agent.image.

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?

Gives a clear use context ('photos of documents, tickets, or labels'), which helps route against the other extract.* siblings. It stops short of naming an explicit alternative or saying when NOT to use it (e.g., for PDFs use extract.pdf), so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: the 15 MB ceiling, support for both text and scanned PDFs, and the conditional source-verification mode that changes each field to {value, source}. It doesn't discuss failure modes or async behavior, keeping it below a 5.

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

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

Three sentences, each earning its place: capability and limits first, output contract second, use cases last. 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?

With an output schema present, full annotation coverage, and 100% schema description coverage, the description only needs to add the non-structural facts, and it does: size limit, accepted input types, conditional field shape, and target document categories. Nothing required to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters (api_key, filename, space_id, file_path, schema_id, file_base64) are already documented in the schema, which sets the baseline at 3. The description adds no parameter-level detail beyond the 15 MB limit; it only alludes to schema_id implicitly via 'using a Claix pdf-json 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 (extract), resource (PDF), and output (structured JSON), with a concrete size ceiling of 15 MB and the accepted input variants (text or scanned). The reader can distinguish it from claix.extract.doc/image/text purely from the PDF scoping, and the example use cases (invoices, contracts, forms, reports) reinforce the intent.

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?

Gives clear usage context via 'Use for invoices, contracts, forms, or reports,' which tells an agent when this tool is appropriate. It stops short of naming alternatives (e.g., use claix.extract.doc for Word documents) or stating when not to use it, so routing between the sibling extract.* tools is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real context: a 300,000-character limit, the log_id return, and the {value, source} shape when source verification is enabled. It stops short of describing retry/error behavior or latency, hence not a 5.

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 action, then layers constraints and return hints in short, scannable sentences. The trailing 'POST /api/txt-json' is mildly redundant for an agent but overall it is dense and free of 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-value detail is not required, and the description correctly limits itself to input constraints, a log_id note, and source-verification behavior. Covers what an agent needs to invoke it correctly, though error/permission behavior 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 baseline is 3. The description still adds value by pinning the content field's role ('no file') and its size ceiling, plus clarifying the output shape the schema produces. Modest but genuine increment over 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+resource ('Extract structured JSON from ... plain text, HTML, or XML') and names the schema mechanism (txt-json schema). The 'already processed' qualifier cleanly separates it from file-based siblings like claix.extract.pdf or claix.extract.doc.

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?

Gives clear context: payload goes in content (no file) and it operates on already-processed text rather than raw documents. It does not explicitly name the alternative siblings or state when NOT to use it, so the routing guidance is implied rather than spelled out.

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=false, destructive=false, idempotent=false, and openWorld=true, so the mutation profile is covered. The description adds useful context such as 'Persistent Mode' for infinity and the default for source verification, but says nothing about duplicate-name behavior or auth requirements beyond what the schema shows.

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 action and endpoint, then enumerates required and optional params in a single dense sentence. No filler, though the parameter list makes it slightly run-on.

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 param details are covered elsewhere. The description supplies the endpoint, required field set, and the source-verification default, leaving only minor gaps like duplicate-name and auth behavior.

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 ten parameters, including enum values, constraints, and the Spanish-named 'cita_por_campo'. The description largely restates required/optional params; its one added value is loosely glossing 'cita_por_campo' as 'source verification' and window_time's Persistent Mode. 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?

Clear specific verb+resource: 'Create a Claix schema', plus the underlying endpoint POST /api/create-schema. It distinguishes itself from claix.schemas.list/delete by naming the create action, though it does not contrast against sibling extract/agent tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance. It never says when a schema must be created (e.g., before extraction) or routes the agent to a related sibling. The parameter listing implies structure but not selection criteria.

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

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

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

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

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

The description is two short sentences. The first sentence immediately states the action, object, and endpoint; the second highlights the required parameter. No filler or redundancy. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Delete a Claix schema'. It specifies the HTTP method and endpoint (POST /api/delete-schema) and scopes the deletion to schemas 'owned by the API key'. This unambiguously distinguishes it from siblings like claix.schemas.create and claix.schemas.list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates a prerequisite ('Requires schema_id') but does not explicitly state when to use this tool versus alternatives or when not to use it. It does not mention looking up schemas first (though the schema parameter description does). Minimal guidance beyond the requirement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is well covered. The description adds context by mentioning the authenticated account and enumerating the exact return fields (id, name, type, etc.), which goes beyond the annotations.

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

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

The description is two sentences, front-loaded with the primary action and return fields, followed by the usage instruction. Every sentence adds value with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with an output schema and strong annotations, the description is complete. It states the resource, authentication context, return fields, and when to call it, leaving no significant gaps for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

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

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'List the Claix schemas available for the authenticated account.' It specifies the verb and resource, lists the returned fields, and explicitly positions itself as a prerequisite for claix.extract.* and claix.agent.* tools, distinguishing it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Call this first whenever you need a schema_id before claix.extract.* or claix.agent.* tools.' This tells the agent when to use this tool relative to its siblings and establishes a clear workflow.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: log_id is null when the answer is in none of the documents, and source-verification mode changes each ia_response item to {value, source} with document_id and file_name. This is exactly the kind of context annotations cannot 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?

Purpose and the sibling contrast are front-loaded, then requirements and return shape. It is dense but somewhat redundant, restating the format enum and the 400-character limit that already appear in the schema, which slightly dilutes conciseness.

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?

Even though an output schema exists, the description usefully characterizes the return shape (user_ask, typed ia_response, log_id) and the conditional source-verification variant, so an agent knows what to expect in edge cases. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the semantic relationship of space_id (the same UUID passed as the optional space_id during extraction), which helps the agent supply the right value rather than any UUID.

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 ('Ask up to 5 typed questions across every document grouped in a knowledge space') and immediately contrasts scope with the sibling claix.window_context.ask: cross-referencing all documents vs a single one. An agent can distinguish it from window_context.ask without opening either 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?

Explicitly names when to use it ('compare, add up, or reconcile data spread over several files') and names the alternative (window_context.ask) plus the condition that distinguishes them ('instead of a single one'). It also states the prerequisite that space_id must match the one used at extraction time.

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=false, idempotentHint=true, destructiveHint=false), and the description does not contradict them. It adds genuine context beyond the annotations: the precondition (no space_id), the specific 400 failure condition, and the cost note ('Free call'). Minor gaps (auth requirements) keep it from the top 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?

Front-loaded with the core action and precondition, then the API endpoint, required inputs, failure mode with remedy, return fields, and cost. No wasted sentences and ideal ordering for an agent scanning it.

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 mutation tool linked to remove_document, the description supplies the precondition, error behavior, alternative routing, and return fields. With an output schema present it needn't detail return values further, and nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the Spanish-language schema already documents all three parameters including UUID formats and examples. The description only restates that document_id and space_id are required, adding no meaning beyond the schema. Baseline 3 applies 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 (assign/add) and resource (a knowledge space to a persisted document) with a scoping constraint ('that has no space_id yet'). It contrasts cleanly with the sibling claix.spaces.remove_document, so an agent can distinguish it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly covers when to use it (document with no space_id yet), when it fails (400 if the document already belongs to a space), and the corrective alternative ('call claix.spaces.remove_document first'). This is the full when/when-not/alternative triad.

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

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

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

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

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

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

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, has an output schema, and the description covers the creation workflow and follow-up usage. It misses nothing critical, but the parameter inaccuracy prevents a perfect score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. However, the description states 'The only field is name,' which contradicts the schema that also defines an optional api_key parameter. This is actively misleading and lowers the score despite the schema being complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Create a knowledge space to group persisted documents', names the resource, gives the endpoint, and lists return values. It also references claix.space_context.ask, which helps distinguish this from sibling tools like claix.spaces.delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides workflow guidance: create a space, pass the returned space_id when extracting, and query the group with claix.space_context.ask. It does not explicitly say when not to use this tool, but the intended usage context is clear.

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

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

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

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

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

The description is brief and front-loaded, with every sentence adding essential information: endpoint, ownership, response, irreversibility, cost, and error behavior. There is no fluff or repetition of schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive operation with one required parameter and an output schema, the description covers all critical aspects: what is deleted, who can delete it, what happens on success and failure, and the irreversible consequence. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% coverage, including a detailed description of space_id and api_key. The tool description adds route-level context but no new parameter-specific meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: delete a knowledge space, constrained to one owned by the API key. It also includes the exact endpoint, making the tool's function unambiguous. It is clearly distinct from siblings like claix.spaces.create and claix.document.delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The ownership constraint and 404 error condition make it clear which spaces are valid targets. It does not explicitly name alternative tools or say when not to use it, but the tool name and sibling context make the intended scope sufficiently clear.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true; the description goes further by disclosing the exact mutation (space set to null), the 400 failure mode, the return payload, and cost ('Free call'). Good added context beyond structured fields, though it doesn't discuss auth requirements or reversibility.

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 action and effect, then endpoint, side effect, failure mode, and return shape. Every sentence adds distinct information with 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?

For a two-parameter idempotent mutation with an output schema, the description covers the action, side effect, failure condition, and return fields. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both document_id and api_key. The description adds only marginal meaning by framing document_id as coming from an extraction with window_context and echoing it in the endpoint path, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Detach) and resource (persisted document from its knowledge space) plus the endpoint and exact side effect (espacio_id set to null). An agent can distinguish this from spaces.add_document and document.delete without opening either 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?

Gives one concrete precondition ('Fails with 400 if it had no space') and notes it is a free call, which helpfully implies usage. However, it never explicitly contrasts this detach-and-unassign operation with the sibling claix.document.delete (permanent removal), leaving the when-to-use-vs-alternative choice to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes beyond them: max 5 questions, 400-char question limit, log_id null when not found, and the source-verification branch producing {value, source} or requires_human_revision. That is genuine behavioral detail not present in 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 dense sentences covering endpoint, prerequisite, input constraints, and return shape – front-loaded and largely waste-free. Slight redundancy with the schema's max-5/400-char constraints costs it a point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Although an output schema exists, the description helpfully summarizes the return contract (user_ask, typed ia_response, log_id null case, verification sources), plus limits and prerequisite. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents document_id, questions, and the format enum with an example. The description restates the format values and the {question, format} shape without adding syntax beyond the schema, 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 (ask typed questions) and resource (a persisted document / window context), with the endpoint shown for anchoring. It implicitly distinguishes itself from claix.space_context.ask via 'document' and the window_context precondition, but never names the sibling explicitly, 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?

Explicitly states the precondition: document_id must come from an extraction with window_context. It gives clear context for when the tool is callable but offers no when-not guidance or direct routing to window_context.get / space_context.ask.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: the exact endpoint, the returned fields, and the fact that it is free. There is no contradiction with annotations.

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

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

The description is three focused sentences: the action and endpoint, the required input origin, and the return fields plus cost. Every sentence contributes useful information, and the key action is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

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

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides 100% coverage, including descriptions, types, formats, and examples for both api_key and document_id. The tool description mostly repeats the provenance of document_id rather than adding significant new semantics, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Retrieve'), names the resource ('persisted document'), and includes the HTTP endpoint (GET /get-document/{document_id}). It also clearly ties the tool to a specific workflow by stating that document_id comes from a window_context extraction, making it easy to distinguish from sibling tools like delete, extract, or ask.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: the tool requires a document_id produced by a window_context extraction, and it notes that the call is free. It does not explicitly name alternative sibling tools or say when not to use it, but the prerequisite is strong enough to guide selection.

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