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

The annotations (readOnlyHint=false, destructiveHint=false) are present and align with the description. The description adds behavioral context beyond annotations, such as lease expiry, conflicting live claim returning 409, and the need to save execution_epoch and lease_expires_at. This makes the tool's behavior transparent and expected.

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

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

The description is concise yet comprehensive, using structured sections 'USE WHEN', 'NOT FOR', and explicit behavioral notes. It avoids redundancy and packs essential information without being overly verbose. The structure enhances readability and preserves information 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?

The description covers all critical aspects: the action (claim/reclaim), when to use, what to save from the return, error handling (409 conflict), and the output (task payload). It also differentiates from related tools, ensuring the agent knows exactly when this tool is appropriate. The description is self-sufficient for safe and 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?

The only parameter, task_id, is fully described in the schema with 'Agent task UUID.' The description also hints at the return value containing execution_epoch and lease_expires_at, which provides additional semantic context. Since schema coverage is 100% and the description adds useful detail, parameter semantics are clear.

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 purpose: 'Claim an available Agent-stage task, or reclaim it after its lease expires.' It specifies the verb 'claim', the resource 'Agent-stage task', and additional nuance about reclaiming. It also distinguishes from sibling tools like talonic_get_agent_task and talonic_heartbeat_agent_task.

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

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

Explicit usage guidance is provided: 'USE WHEN: ready to process a task' and 'NOT FOR: merely inspecting work (use talonic_get_agent_task) or extending an active lease (use talonic_heartbeat_agent_task)'. Behavioral details about conflicting claims (HTTP 409) and successful claims (returns task payload) further clarify when and how to use the tool.

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

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

Annotations already indicate non-read-only and non-destructive behavior. The description adds valuable context like cost ('cheap per call, free tier'), confidence-based review thresholds, and mentions of returned metadata. No contradictions 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 lengthy but well-structured with clear sections (USE WHEN, NOT FOR, BY NAME, ARGS, COST, RETURNS). It front-loads the core purpose. Every sentence adds value, though some repetition could be trimmed. It earns high marks for organization.

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 11 parameters (0 required) with complex interdependencies, the description covers all document source options, schema definition methods, auto_schema, instructions, and optional output fields. It also describes the return structure with confidence scores and hints for handling low confidence. Output schema enriches this, but the description provides essential context for a complete picture.

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 adds meaning by explaining mutual exclusivity rules (schema vs schema_id vs auto_schema), recommending usage for each document source, and clarifying optional parameters like instructions and include_markdown. This is a meaningful addition 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's purpose as converting unstructured documents into structured JSON. It specifies the verb ('turn into'), resource ('document'), and explicitly distinguishes it from sibling tools like talonic_to_markdown and talonic_search/talonic_filter by listing use cases and exclusions.

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 when-to-use patterns ('USE WHEN: extract data from this document...'), exclusions ('NOT FOR: full plain text...'), and a prerequisite step ('BY NAME: if the user names a file, call talonic_search first'). This is excellent guidance for an AI agent.

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 and idempotent hints, so this is known to be safe. The description goes well beyond that by disclosing the one-row-per-bound-occurrence model, the provenance structure, the Sources-IAM filtering, and the 'exactly one of field_id or name' constraint. It also exposes the pagination limit and current-value semantics, which are not visible from annotations alone.

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

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

The description is well-structured with labeled sections: a purpose sentence, USE WHEN, NOT FOR, ARGS, and RETURNS. Every sentence carries actionable information, and the most important scoping information is front-loaded. Despite its length, there is 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?

The description is self-sufficient even though there is no output schema. It enumerates the full response shape including pagination and provenance, states the IAM filtering behavior, and covers parameter constraints. Combined with the sibling differentiation and use-case guidance, an agent has everything needed to call this tool 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 baseline is 3. The tool description adds the crucial constraint that exactly one of field_id or name must be provided, and clarifies that document_id restricts to a single document. It does not need to restate the schema's already-rich parameter descriptions, and the additional constraint meaningfully improves invocation correctness.

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

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

The description opens with a specific verb and resource, 'Read a field's CURRENT VALUES across documents, with provenance', and defines the row granularity precisely. It also distinguishes itself from siblings by explicitly naming what it is NOT for: talonic_filter and talonic_get_document, so an agent can disambiguate immediately.

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

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

The description provides an explicit USE WHEN section with concrete triggers ('what are all the X across my documents', tabulating/aggregating a concept, wanting evidence behind a value) and a NOT FOR section naming the exact alternative tools. This is exemplary routing guidance that leaves no ambiguity.

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 give readOnlyHint and destructiveHint. Description adds: conditions are AND-ed, operator-specific behaviors (is_empty takes no value), numeric guard (check dataType first), text field name resolution with warnings, and instruction to surface warnings. No contradiction.

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

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

The description is well-structured with clear sections (USE WHEN, NOT FOR, ARGS, TEXT FILTERS, NUMERIC GUARD, RETURNS) and front-loaded. It's somewhat long but each sentence adds value, appropriate for the complexity.

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 complexity (6 params, nested objects, many operators) and existence of output schema, the description covers all critical aspects: purpose, usage, parameter details, edge cases, warnings, return structure. Nothing 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%, but description adds deep semantics: explains field/field_id exclusivity, operator list, value/value_to for between, data types, and text filter resolution. This goes well beyond schema descriptions.

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

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

The description clearly states 'Find documents by their extracted field VALUES using composable conditions' and gives an example. It distinguishes from siblings talonic_search and talonic_get_document in the 'NOT FOR' section.

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 says 'USE WHEN: value-based criteria on extracted fields' and 'NOT FOR: free-text / concept search (use talonic_search); a single document by id (use talonic_get_document).' Also provides guidance on numeric guard and warning handling.

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

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

Beyond annotations, the description discloses that the tool is read-only with no LLM cost, performs semantic + lexical retrieval, can resolve concepts even when the field is captured under a different name, and restricts document_ids as a hard server-side scope. It also explains the ranked output structure, adding meaningful behavioral context beyond the safety hints already present.

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

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

The description is long but densely structured with clear USE WHEN, NOT FOR, ARGS, and RETURNS sections. Every section earns its place, and the core purpose is front-loaded. The formatting makes it easy for an agent to scan and extract invocation decisions quickly.

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

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

With no output schema, the description thoroughly covers return value shape: ranked FIELDS, VALUES, DOCUMENTS, and PASSAGES planes, including key fields and sample values. It also covers all parameters, usage context, exclusions, and safety behavior, leaving little ambiguity for an agent deciding whether and how to call this tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by clarifying query should be in the user's own words, stating top_k's default of 10, and emphasizing that document_ids is a hard scope enforced server-side. These details go beyond the schema's type and constraints.

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: locate the real data behind a natural-language concept using semantic and lexical retrieval, mapping phrases to fields, values, documents, and passages. It clearly distinguishes this discovery tool from siblings by framing it as the pre-query resolution step and by noting it works even when fields are named differently.

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 USE WHEN conditions: uncertainty about which field holds a concept, empty or ambiguous results from talonic_list_fields/talonic_search, or when answers may live in prose. It also gives NOT FOR exclusions naming talonic_field_values and talonic_filter, making alternative selection unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is covered. The description adds value by stating the data is immutable and audited, and mentions the timeout_fallthrough return field, which is non-annotated behavioral context. A small deduction because it doesn't elaborate on what timeout_fallthrough means or other edge cases.

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

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

The description is compact, front-loaded with purpose, and uses clear labeled sections (USE WHEN / NOT FOR / ARGS / RETURNS). Every sentence provides actionable information with no repetition or fluff.

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

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

For a single-parameter read-based tool with rich annotations and 100% schema coverage, the description covers the purpose, usage, and return fields. The only gap is not explaining the 'timeout_fallthrough' field, but that's an output detail rather than a functional requirment. It doesn't need an output schema since it lists return keys.

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 covers task_id fully with format and description, so baseline is 3. The description just says 'ARGS: task_id' which adds no new semantics. That's acceptable 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 fetches an Agent-stage task's immutable input snapshot, instructions, and output contract. It names the specific resource ('Agent-stage task') and distinguishes it from siblings like claim/submit by explicitly naming those alternatives. The verb 'Fetch' is concrete and unambiguous.

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

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

The description provides explicit USE WHEN and NOT FOR guidance, naming tailonic_claim_agent_task and tailonic_submit_agent_task as alternatives. This fully clarifies the tool's position in the workflow and prevents misuse.

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

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

Annotations already mark it read-only. The description adds value by detailing returned fields and noting that projected runway is -1 when no recent usage. 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?

Description is concise: a single introductory sentence followed by structured USE WHEN, NOT FOR, ARGS, and RETURNS sections. Every sentence is informative and earns its place.

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

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

Given the tool's simplicity (read-only, no parameters, documented output schema), the description covers all necessary context: what is returned, when to use, and what not to use for. No gaps.

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

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

Input schema has 0 parameters (100% coverage). Description explicitly states 'ARGS: none.' Baseline for 0 parameters is 4, and the tool meets that standard without needing further parameter documentation.

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

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

The description clearly states it reads the workspace's Talonic credit balance, EUR value, tier, 30-day burn, and projected runway. The verb 'Read' and specific resource details make purpose unambiguous. It naturally distinguishes from credit-related queries that would go to talonic_extract.

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

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

Explicit USE WHEN and NOT FOR sections provide clear guidance: use when user asks about credits/budget or before a large batch; not for per-call cost (pointing to talonic_extract). This effectively differentiates from sibling 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. The description adds valuable behavioral details: the status lifecycle, terminal failure statuses, and instructions to stop polling and report failures. No contradiction.

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

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

The description is concise and well-structured with clear sections (USE WHEN, NOT FOR, BY NAME, ARGS, RETURNS). Every sentence adds value, and the formatting aids readability.

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 (1 parameter, output schema exists), the description covers purpose, usage, behavior, parameter origin, return values, and status lifecycle. It also integrates with siblings for complete workflow 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 coverage is 100% and describes the document_id parameter well. The description adds context about getting the ID from previous responses, but does not provide new semantic meaning beyond what the schema offers. Baseline 3 is appropriate.

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

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

The description clearly states 'Fetch a single document's metadata and processing status from the workspace.' It uses a specific verb and resource, and distinguishes itself from sibling tools (talonic_to_markdown, talonic_extract) by stating what it is NOT for.

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

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

Explicit 'USE WHEN' and 'NOT FOR' sections provide clear context. It specifies when to poll after upload, when to use alternatives, and even instructs to call talonic_search first if user names a file.

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, and non-destructive hints, but the description adds meaningful behavioral detail beyond those: the name resolution order, the fact that the response reports which resolution arm matched, and the effect of include_history. This is context annotations cannot 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?

The description is structured into clear labeled sections (USE WHEN, NOT FOR, ARGS, RETURNS) and every sentence carries meaningful information. Nothing is redundant with the schema, and the content is front-loaded with the core purpose before usage guidance.

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 no output schema, the description supplies the full response shape, resolution behavior, history behavior, and sibling routing. Combined with 100% schema coverage and strong annotations, an agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter in detail. The description adds the crucial exclusivity rule ('exactly one of field_id or name') and clarifies that resolution follows to the live concept, plus the response's resolution field behavior, which 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 states a specific verb and resource ('Get the CONCEPT CARD for one Field Registry field') and enumerates exactly what the card contains. It also explicitly distinguishes itself from siblings by naming talonic_list_fields and talonic_field_values in the NOT FOR clause.

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 gives three concrete decision triggers, and NOT FOR names the two sibling tools to use instead. This leaves no ambiguity about when to select this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by stating it is public and does not spend credits, which is consistent with the annotations. No contradictions.

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

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

The description is concise and well-structured with clear headings (USE WHEN, NOT FOR, ARGS, RETURNS). Every sentence is informative and earns its place. No wasted words.

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

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

Given zero parameters and an output schema (though not shown), the description fully covers what the agent needs: purpose, usage, and return format. The annotations provide safety context, making it 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?

With zero parameters and 100% schema coverage, baseline is 4. The description mentions 'ARGS: none' and explains the return structure (currency, credits_per_eur, etc.), which adds meaning beyond the empty 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 uses a specific verb 'Read' and identifies the resource 'Talonic's machine-readable credit pricing catalog'. It clearly distinguishes from sibling tools like talonic_get_balance and talonic_get_usage by stating its purpose is for estimating costs.

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 provides use cases ('USE WHEN: estimating cost'), non-use cases ('NOT FOR: balance/usage'), and names alternative tools. This leaves no ambiguity about when to invoke this tool.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing the return structure (period_days, total_credits, by_function) and the days parameter clamping. This extra context 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?

The description is concise, well-structured with clear sections (lead sentence, USE WHEN, NOT FOR, ARGS, RETURNS). Every sentence is purposeful and front-loaded with key 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?

Given the tool's simplicity (one optional parameter, read-only operation with annotations and output schema implied by the return description), the description fully covers when, why, and what to expect. It is complete for effective use.

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

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

Schema coverage is 100%, so baseline 3. The description repeats the parameter's default and clamping, adding slight value over the schema description. However, no additional meaning beyond what the schema already conveys.

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 'Read the workspace's per-function credit consumption' using a specific verb and resource. It distinguishes from siblings by explicitly stating it is for seeing where credits went, not for balance or pricing.

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 includes explicit 'USE WHEN' and 'NOT FOR' sections, directing the agent when to use this tool and providing alternatives (talonic_get_balance, talonic_get_pricing). This makes the usage context crystal 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?

It discloses the important behavioral outcome that stale or foreign claims return HTTP 409, which is useful beyond the annotations. The lease-extension mutation is consistent with readOnlyHint=false, though the description does not mention success response details or other failure modes.

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

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

The description is compact, well-structured, and front-loaded with the core purpose. USE WHEN, NOT FOR, and ARGS/ failure behavior sections each add value without redundant 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 low-complexity two-parameter tool, the description covers purpose, usage conditions, alternatives, and failure behavior. It stops just short of perfect completeness by not stating what a successful heartbeat returns, but this is not essential for choosing or invoking the operation.

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

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

The input schema already provides a 100% covered description, so the baseline is a solid 3. The tool description raises that by explaining the execution_epoch comes from the claim, that heartbeats must happen before expiry, and that foreign claims are rejected.

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 ('Extend the lease') with a specific resource ('a claimed Agent-stage task'), making the operation immediately clear. It also distinguishes this tool from the sibling claim and submit tools.

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

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

The description gives explicit USE WHEN and NOT FOR guidance, including concrete sibling alternatives: talonic_claim_agent_task and talonic_submit_agent_task. This tells the agent exactly when the tool is appropriate and when it is not.

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 readOnlyHint and destructiveHint annotations, the description reveals important runtime behavior: calls are direct with no model in the loop, denied capabilities return errors naming the required capability, and the platform re-checks every call. It also documents the return envelope and optional hard-scoping behavior, adding substantial transparency without contradicting 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 well-structured with USE WHEN, NOT FOR, ARGS, and RETURNS sections. Every section earns its place, and the front-loaded purpose sentence immediately conveys the core behavior. Despite covering a generic dispatch tool, it avoids unnecessary fluff.

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

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

For a generic invoke tool with no output schema, the description is remarkably complete: it explains how to discover invokable tools, how to construct arguments, what the return shape is, and how errors are surfaced. The combination of description, schema, and annotations gives an agent everything it needs to select and call this tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description adds value by clarifying that args must exactly match the target tool's input_schema, that name comes from talonic_list_agent_tools, and that document_ids acts as a hard scope for scope-aware tools—useful semantic context beyond the raw schema.

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

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

The description uses a specific verb and resource: "Invoke ONE named tool from the platform's agent tool registry directly." It also differentiates from dedicated tools via the explicit "NOT FOR" clause and presents concrete examples like query_data and describe_data, making the tool's role unmistakable.

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

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

The description explicitly states when to use the tool (when talonic_list_agent_tools shows can_invoke: true) and when not to use it (when a dedicated talonic_* tool exists). It also tells the agent to pass args exactly as the target tool's input_schema declares, which is actionable routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is known. The description adds that it 'RETURNS: metadata only plus pagination.next_cursor,' clarifying the scope of results and the absence of payload data, which goes beyond the annotation. This additional context is valuable.

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

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

The description is compact and well-structured: it starts with a clear purpose, then uses labeled sections (USE WHEN, NOT FOR, ARGS, RETURNS) to convey key information without redundancy. Every sentence earns its place.

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

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

With no output schema, the description explicitly states the return value ('metadata only plus pagination.next_cursor'), filling that gap. It also covers scope, filters, pagination, and alternatives, making the tool behavior fully understandable for an agent. The tool is simple, and the description addresses all necessary aspects.

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

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

Schema coverage is 100%, with each parameter (limit, cursor, status) already described in the schema. The description's mention of 'optional status, limit, and cursor' adds no new meaning, though it does reference pagination.next_cursor which ties to the cursor parameter. Since the schema does the heavy lifting, a 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 clearly states 'List Agent-stage tasks visible to this Talonic workspace credential,' specifying the exact action (list), the resource (agent tasks), and the scope (visible to workspace credential). It also distinguishes itself from siblings by noting NOT for reading payload or taking a lease, making it 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?

Explicit USE WHEN guidance is provided: 'looking for external-agent work to process; begin with status available.' NOT FOR exclusions mention specific alternatives (talonic_get_agent_task and talonic_claim_agent_task), giving clear when-to-use vs when-not-to-use instructions.

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 already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description goes beyond this by revealing the return shape, the per-credential can_invoke field, that schemas may be included conditionally, and that this is the discovery entrypoint for capabilities not covered by direct talonic_* tools.

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

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

The description is well-structured with clear USE WHEN, NOT FOR, ARGS, and RETURNS sections, making it easy to scan. It is slightly longer than strictly necessary because ARGS duplicates the input schema, but the structure and routing guidance justify most of the length.

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

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

With no output schema, the description compensates by explicitly specifying the return contract including tools array fields, invocable_count, and totalCount. It also explains the credential-aware behavior, default parameter values, and when to use/avoid the tool, so an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, with both parameters documented in the input schema. The ARGS section mostly restates the schema information, adding only the default-value emphasis and a slightly clearer phrasing of each flag's effect, which is marginal value.

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

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

The description uses a specific verb and resource: 'List the platform's agent tool registry', with concrete examples of what is included and that each entry carries its input schema and invocation eligibility. It clearly distinguishes itself from sibling tools like talonic_list_fields and talonic_search by stating it returns registry-level metadata rather than field/document data.

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

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

The description explicitly provides 'USE WHEN' and 'NOT FOR' sections, naming exact alternative siblings and the conditions that route to them. It even tells the agent the next step after listing: call talonic_invoke_agent_tool with the tool name and args.

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 readOnly/idempotent/destructive safety; the description adds genuinely useful behavior: merged/superseded rows are hidden by default, maturity semantics for stable vs candidate concepts, and cursor pagination with a return-shape listing. It could also mention auth requirements or rate limits, but those are not necessary for this read-only listing tool.

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

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

The description is front-loaded with purpose, then structured into USE WHEN, NOT FOR, ARGS, and RETURNS. Every section earns its place, and the ARGS section is a compact summary rather than a full schema dump.

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

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

With no output schema, the RETURNS field list is essential and present. The description also covers pagination, default behavior for superseded rows, when to use the tool, and how it relates to sibling tools; no significant calling context is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds guidance beyond the schema by explaining why to prefer core/proven maturities and what include_superseded=false means semantically ('you never see two ids for one concept'). This is useful parameter-level context without needing to restate schema details.

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 ('List') with an explicit resource ('the workspace's Field Registry') and defines what those concepts are. It also distinguishes itself from siblings by stating it is not for locating documents (talonic_search) or filtering by value (talonic_filter), so an agent can select it correctly.

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 USE WHEN block gives concrete triggers ('need to know WHAT data exists... need the exact field id for talonic_get_field / talonic_field_values') and the NOT FOR block names the sibling alternatives. This is explicit routing guidance rather than implied usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by stating it returns data[] of schema summaries, that full field definitions are omitted, and that there are no arguments. This provides behavioral detail 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 concise with three clear sections: purpose, usage guidance, and returns/args. No unnecessary information. Every sentence 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?

For a simple listing tool with no parameters and minimal complexity, the description covers all necessary information: what it returns, how to use it, and where to find additional details (resource). Output schema exists but the description adequately summarizes the return.

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?

There are no parameters, and the description confirms 'ARGS: none.' The schema coverage is effectively 100%. With 0 parameters, the baseline is 4, and the description meets that.

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 starts with a specific verb ('List') and resource ('saved schemas'), and details the output fields (id, short_id, name, description, version, field_count). It distinguishes from sibling tools by noting that full field definitions are omitted and directing users to the talonic://schemas resource for those.

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 when to use ('what schemas do I have', find a reusable schema before extracting) and when not to (one-off extraction with inline schema, directing to talonic_extract). This provides clear alternatives and context.

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

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

The description discloses full workflow: returns upload_url, document_id, expires_at; after user uploads, poll talonic_get_document until status 'completed', then call talonic_extract; handles failure statuses. Annotations (readOnlyHint=false) are not contradicted and are supplemented by this detailed 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?

The description is well-structured with sections: main description, USE WHEN, NOT FOR, ARGS, RETURNS. It is front-loaded with key information, and every sentence adds value. No unnecessary words or repetitions.

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 complexity (one parameter, no enums, output schema exists), the description completely covers the input, output, and subsequent steps. It provides a workflow for polling and error handling, which is essential for an agent to use the tool correctly. Sibling tools are listed for context.

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

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

The schema already describes filename with minLength and a brief description. The description adds that filename should include extension and is used to pre-allocate and infer MIME type, providing extra meaning beyond the schema. With 100% schema coverage, baseline is 3; added value justifies 4.

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 purpose: 'Get a browser upload link the user opens to add a file to their workspace' and specifies it returns both the link and a pre-allocated document_id. It uses specific verbs and resources, and the context distinguishes this from sibling tools like talonic_extract.

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

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

Explicit 'USE WHEN' and 'NOT FOR' sections provide clear guidance on when to use this tool versus alternatives (e.g., 'hosted/sandboxed clients' or 'files too large'), and when not to (e.g., document already in workspace or file on public URL). The description also directs the agent to talonic_extract for public URLs.

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 indicate destructiveHint=false, which aligns with saving non-destructive. Description adds that it saves to workspace and returns id/short_id. Could mention if same name overwrites, but overall sufficient.

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?

Extremely concise: one sentence purpose, then usage, then args, then returns. No wasted words.

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

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

All necessary context provided given schema coverage and output description. Parameter count, required fields, and return value all addressed.

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?

Input schema has 100% coverage. Description adds value by explaining definition accepts JSON Schema or flat map, and that return includes id and short_id for later use.

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 verb 'Save' with specific resource 'a reusable schema to the workspace'. Distinguishes from sibling talonic_extract by stating it's for reuse across documents, not one-off extractions.

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 'USE WHEN' and 'NOT FOR' with direct alternative (talonic_extract). Provides clear context for when to choose this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds critical behavioral details: matching is literal keyword, sentences/plurals return empty, and fields must have filterable:true to work with talonic_filter. No contradiction.

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

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

Efficient structure: first sentence states purpose, then details matching behavior, then usage guidelines, then parameter description, then returns listing. Every sentence serves a purpose. No wasted words.

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

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

Given the output schema exists, the description is complete enough. It covers purpose, behavior (literal matching, empty results), usage constraints, return types with actionable ids, and integrates with sibling tools. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by clarifying that query must be a short singular keyword or exact filename, and gives examples like 'invoice' vs 'invoices'. Also states limit default is 5. This utility boosts the score above baseline.

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

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

The description uses specific verbs and resources: 'Find documents, fields, schemas, or sources'. It clearly distinguishes from siblings by noting that this tool is for keyword search across all types, while talonic_filter is for structured filters.

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

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

Explicit conditions: 'USE WHEN: the user names or describes a document without an id... NOT FOR: structured field-value filters (use talonic_filter).' Also provides retry advice for empty results, which is actionable context.

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 adds meaningful behavioral context beyond the annotations: outputs are validated transactionally before anything is written, the execution epoch must come from a successful claim, stale epochs are rejected, and the document is resumed. This is strong for a write tool even though the annotations do not signal danger or 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?

The description is compact, front-loaded with the core purpose, and organized with 'USE WHEN', 'NOT FOR', and 'ARGS' sections. Every sentence contributes actionable guidance with no wasted words.

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

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

For a tool with no output schema, the description covers the core workflow context: eligibility, arguments, validation behavior, contract enforcement, and resume semantics. It stops short of describing the response or potential failure modes after submission, but the key operational context is present.

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

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

The input schema already documents all four parameters, so the baseline is 3. The description adds semantically valuable guidance by clarifying that outputs must be keyed exactly by the declared field key, that the optional summary is allowed, and that execution_epoch comes from a successful claim, which enriches the schema-only 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?

The description clearly states a specific verb ('Submit') and resource ('declared output fields for a claimed Agent-stage task') and explains the resulting effect ('resume the parked document'). It also explicitly distinguishes itself from the sibling tool talonic_heartbeat_agent_task via the 'NOT FOR' clause.

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 'USE WHEN' and 'NOT FOR' guidance, stating this tool is appropriate when processing is complete and every required output is ready, and inappropriate for undeclared fields or partial maintenance. It even names the alternative tool, making the boundaries unambiguous.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), description adds that file inputs ingest and consume credits while document_id does not, and different input methods have different costs.

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?

Well-structured with sections, front-loaded with main purpose. Every sentence adds value. No redundancy.

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

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

Given output schema exists, description covers return values (document_id and markdown). Addresses complex input choices and usage scenarios. Complete for tool complexity.

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

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

Schema coverage is 100% with good descriptions. Description adds hierarchy: prefer document_id, then file_url, then file_data+filename for small local files. Provides selection guidance beyond 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?

Description clearly states it gets OCR-converted markdown text of a document. Uses verb 'Get' and specifies resource. Distinguishes from sibling talonic_extract for structured fields.

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

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

Explicit sections: USE WHEN for full text/summarize/translate, NOT FOR structured fields, BY NAME instructs to first call talonic_search. Provides clear decision rules.

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