Talonic - Data Extraction MCP

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

The description discloses internal mechanics: planning over the structured field plane, running read-only SQL over extracted cells, reading document text, and grounding claims in source spans. It also reveals the cost ('Consumes credits') and the asynchronous behavior with instructions to call talonic_get_answer if status is still 'processing'. This goes well beyond the annotation hints.

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 organized into clear sections: purpose, when to use, when not to use, args, and returns. The purpose is front-loaded, and every sentence carries routing, invocation, or behavior information. Despite being long, the length is justified by the tool's complexity and there is no filler.

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

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

Given the tool's complexity and the absence of an output schema, the description is self-sufficient: it covers parameters, scoping, return shape, cost, verification, and the async continuation path. The explicit instruction to call talonic_get_answer when status is 'processing' closes the loop for correct 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 description coverage is 100%, and the schema already documents all parameters including ANDed scope semantics, wait_seconds default, and output_format behavior. The description's ARGS section provides a useful at-a-glance summary but little new semantic information beyond the schema, so the baseline score of 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 opens with a specific verb and resource ('Ask a natural-language question over the workspace's documents') and names the deliverable: a cited, verified markdown answer. It clearly distinguishes this tool from sibling tools by describing it as for open, multi-field reasoning questions. There is no ambiguity about what the tool does.

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

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

The description has explicit USE WHEN and NOT FOR sections that name the sibling alternatives (talonic_field_values, talonic_filter, talonic_find_data) and even note that they are free. It states concrete conditions for choosing this tool over those alternatives, so an agent can route correctly without guessing.

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 (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?

Even though annotations already mark this as not read-only and not destructive, the description adds significant behavioral context: claiming is the payload fetch, leases can expire and be reclaimed, a conflicting live claim returns HTTP 409, and auth failures return 403 with specific error codes (decide_grant_required, insufficient_scope, insufficient_tier) and instruct the agent not to retry. This goes well beyond what annotations alone 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 long but tightly structured with clear labels: the core behavior, USE WHEN, NOT FOR, and AUTH. Every sentence carries operational value—there is no filler or repetition. The most critical facts (claiming fetches the bundle, save the lease fields, use first_cursor) are 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?

Given that there is no output schema, the description compensates by explicitly naming the decision bundle fields, the package descriptor fields, the meaning of null first_cursor, the follow-up tool to use, conflict behavior, and authentication requirements. This is complete enough for an agent to invoke the tool correctly without further inference.

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

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

The schema covers 100% of the parameter information: task_id is described as 'Decision task UUID' with format and pattern constraints. The description adds workflow context but does not add new parameter-level semantics beyond the schema. With full schema coverage, the baseline of 3 is appropriate; there is no gap to compensate for.

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

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

The description states a specific action ('Claim an available decision task'), the target resource, and a concrete outcome ('receive the decision bundle') with a detailed list of returned fields. It explicitly distinguishes itself from siblings by noting that claiming is the payload fetch and there is no separate get. An agent can clearly tell this apart from talonic_read_decision_package, talonic_heartbeat_decision_task, and talonic_submit_decision_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?

The description provides explicit USE WHEN guidance ('ready to decide a listed task') and a NOT FOR section naming the exact alternatives: talonic_heartbeat_decision_task and talonic_submit_decision_task. It also provides workflow direction: save execution_epoch and lease_expires_at, then read with talonic_read_decision_package starting at first_cursor. This leaves no ambiguity about when to invoke this tool versus its siblings.

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, and the description reinforces a read-only data-retrieval behavior. Beyond annotations, it discloses provenance details, one-row-per-occurrence semantics, the return envelope, pagination, and that rows are Sources-IAM filtered for the caller. This is rich behavioral context with 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 USE WHEN, NOT FOR, ARGS, and RETURNS sections, and the core behavior is stated in the first sentence. Every sentence adds decision-relevant information; there is 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 no output schema, the description carries the burden of explaining the return shape, and it does so in useful detail: field metadata, data array fields, nested provenance fields, links, and pagination. It also covers all parameters, scoping behavior, and IAM filtering, making it complete enough 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 coverage is 100%, so the schema already documents each parameter. The description adds meaningful selection-semantics beyond the schema by stating 'exactly one of field_id or name' and summarizing the optional filters, value as a case-insensitive contains filter, limit cap, and cursor. This compensates for the schema's lack of required-parameter 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?

Description opens with a specific verb and resource: 'Read a field's CURRENT VALUES across documents, with provenance — one row per bound occurrence.' It names the exact output granularity and distinguishes itself from siblings in NOT FOR, explicitly calling out talonic_filter and talonic_get_document. An agent can understand what this tool does and how it differs from nearby 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?

Contains explicit USE WHEN guidance ('what are all the X across my documents', tabulate/aggregate, need evidence behind a value) and NOT FOR exclusions with sibling names. This gives the agent clear decision criteria for 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 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes beyond that by specifying the return structure (ranked planes: FIELDS, VALUES, DOCUMENTS, PASSAGES) and adding operational context: 'Read-only, no LLM cost.' It also notes that results are 'ready handles for the next call,' which tells the agent the output is directly reusable. 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 long but every sentence earns its place, organized with bolded section headers (USE WHEN, NOT FOR, ARGS, RETURNS) that make scanning easy. The core purpose is front-loaded in the first sentence, and the rest provides structured, non-redundant detail. No filler or tautology.

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 complex (semantic retrieval across multiple planes, no output schema), and the description fully compensates. It explains what each return plane contains, how to interpret the results (ranked, with handles for subsequent calls), and the hard scope semantics of document_ids. With no output schema, this description carries the full burden and meets it. Also covers safety via annotations and adds the 'no LLM cost' note, which is operationally important.

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%: each parameter already has a description in the schema (query, top_k, document_ids). The description reinforces these by restating query as 'the concept, in the user's words,' top_k default as 10, and document_ids as a hard scope. This adds minor nuance beyond the schema (e.g., 'hard scope' and default) but largely repeats it, so it stays above baseline 3 without reaching 5.

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 ('locate') and resource ('real data behind a natural-language concept'), then immediately explains the mechanism (semantic + lexical retrieval) and the scope (fields, values, documents, passages). It explicitly distinguishes itself from siblings by naming talonic_list_fields / talonic_search and stating when those fall short, so an agent can select it unambiguously.

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

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

It provides a dedicated 'USE WHEN' section that lists three concrete triggers (unsure which field holds a concept, sibling tools returned empty/ambiguous, answer may live in prose) and a 'NOT FOR' section naming two alternatives (talonic_field_values, talonic_filter). This is explicit, actionable routing guidance with no room for 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 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: polling cadence, expected terminal statuses ('completed' or 'error'), and the processing response shape with poll_hint. This is meaningful supplementary disclosure.

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 uses labeled sections (USE WHEN, NOT FOR, ARGS, RETURNS) that make scanning easy. Every sentence contributes useful information with 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?

For a single-parameter polling tool, the description is complete: it explains when to use it, what argument to pass, what the return envelope looks like, and how to handle the processing state. Annotations cover safety and idempotency, and the schema covers the parameter format. Nothing essential 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 ask_id as 'From talonic_ask.' The description reinforces this by saying ARGS: ask_id and explaining it comes from a talonic_ask response, but it does not add substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Poll') and resource ('an ask for its answer'), and explicitly distinguishes itself from talonic_ask by stating it is for asks that were still processing. This makes the tool's purpose unmistakable and separates 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 USE WHEN conditions (talonic_ask returned status 'processing' with an ask_id) and a NOT FOR exclusion (asking a new question via talonic_ask). This gives an agent clear decision criteria for 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 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds real behavioral context beyond that: the name-resolution pipeline (canonical name → spelling fold → merge aliases → synonyms → case-insensitive fallbacks), the fact that the response reports which resolution arm matched, and that include_history appends the curation trail. No contradiction with annotations exists.

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

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

The description is dense but well-organized with labeled sections: definition, USE WHEN, NOT FOR, ARGS, and RETURNS. The most important usage information is front-loaded, and each section earns its place. The small overlap between the opening summary and the RETURNS key list improves scannability rather than adding bloat.

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

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

For a tool with no output schema, the description provides the full return shape and the conditional presence of resolution and history fields. It also explains the resolution behavior and the exact-one-argument rule. The main gap is missing failure semantics, such as what happens when a supplied name or field_id cannot be resolved, which would help an agent handle the not-found case.

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 a meaningful nuance the schema does not encode: exactly one of field_id or name must be provided, even though the schema marks none as required. It also clarifies resolution order and the conditional return fields, going slightly beyond the per-parameter 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 states a specific verb ('Get'), a specific resource ('CONCEPT CARD for one Field Registry field'), and an explicit inventory of what the card contains. It further distinguishes itself from siblings by naming talonic_list_fields and talonic_field_values in the NOT FOR section. An agent can confidently tell this apart from the other field-related 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 USE WHEN section gives three concrete triggering scenarios, and the NOT FOR section explicitly names alternatives and what they are for. It also adds the crucial invocation constraint that exactly one of field_id or name should be supplied. This is explicit, actionable guidance with clear 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 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 establish readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat those. It adds useful context by explaining that status is normalised and that progress includes documents and pipeline phases, plus the terminal states to watch for. It does not add much on failure modes or rate limits, but the existing annotations cover the safety profile.

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-organised with clear labels for use, exclusions, arguments, and return shape. Every section contributes directly to correct selection and invocation, with no wasted words. The structured format makes it easy for an agent to parse 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?

Despite having no output schema, the description provides a detailed return shape including progress, optional fields, and error_message. It also explains the polling loop and terminal statuses, giving an agent everything needed to drive the 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?

The schema only lists two optional UUID parameters, so the description materially clarifies them by stating 'exactly one' and mapping each parameter to the right run_kind and envelope. This is critical usage information the schema itself does not encode, making the parameter semantics substantially clearer.

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 action, 'Poll a Spec run', and enriches it with the actual value returned: normalised status, document-level progress, and per-phase progress for pipelines. It also names sibling alternatives it is not, such as talonic_get_run_results and talonic_run_spec, so the agent can distinguish it 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?

It gives an explicit 'USE WHEN' condition with concrete polling cadence and terminal statuses, and an explicit 'NOT FOR' section naming the relevant alternatives. This leaves no ambiguity about when to choose this tool versus its siblings.

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 valuable behavioral context: partial rows are readable while processing, held/pending-review cells serialize null, and the include parameter makes the payload heavier. It doesn't describe pagination behavior in depth, but the RETURNS section covers the response shape.

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 dense but well-structured with clear USE WHEN / NOT FOR / ARGS / RETURNS sections. Every sentence earns its place: the first sentence defines the resource, the second gives the trigger condition, the third excludes alternatives, the fourth explains argument selection, and the fifth documents the return shape. 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 read-only, idempotent tool with 100% schema coverage and a detailed RETURNS section, the description is complete. An agent knows exactly when to call it, which arguments to use, what the response looks like, and how it differs from siblings. The absence of an output schema is compensated by the explicit RETURNS block.

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 6 parameters. The description adds meaning beyond the schema by explaining the run_kind distinction (pipeline_id for run_kind 'pipeline' vs run_id alone for run_kind 'run'), the scoping relationship between run_id and pipeline_id, and the semantic effect of include (heavier payload). This goes beyond the schema's per-parameter 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 opens with a specific verb and resource: 'Read a Spec run's structured rows — one row per document with the Spec's fields as clean values... plus the column definitions.' This clearly distinguishes it from siblings like talonic_get_run (progress) and talonic_field_values (per-field provenance).

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 it ('USE WHEN: talonic_get_run reports completed...'), what it is not for ('NOT FOR: progress... or per-field provenance...'), and names the alternative tools. It also explains the ARGS selection logic (pipeline_id vs run_id) and optional include values.

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 meaningful behavioral context beyond annotations: nodes[] is 'the rail as authored, in editing order' while phases[] is 'the compiled execution plan, in run order', with validation checkpoints expanding to one phase per gate, explaining why the lists differ. It also discloses that include_versions returns versions newest first with specific fields. This adds real value beyond the structured annotations.

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

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

The description is longer than average but tightly organized with labeled sections: USE WHEN, NOT FOR, ARGS, RETURNS. Each section earns its place and the most important scoping information is front-loaded. No filler or repetition of obvious details.

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

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

There is no output schema, so the RETURNS section carries the full burden of describing the response shape, and it does so exhaustively ('{ id, name, description, schema_id, version, materialized_version, materialized_at, field_count, node_count, schema, nodes[], phases[], fields[], links }' plus optional versions[]). Combined with the usage guidance and parameter details, nothing an agent needs to correctly call this tool 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 parameters. The description nonetheless adds value: it specifies spec_id comes from talonic_list_specs and details exactly what include_versions adds ('published versions newest first, each { version, content_hash, created_at, is_materialized }'). This exceeds the schema's bare definitions, though the baseline is already solid.

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 one Spec's structure') and immediately clarifies scope: identity, version state, schema, nodes[], phases[], and fields[]. It actively distinguishes itself from siblings by naming talonic_list_specs and talonic_run_spec in the NOT FOR section. An agent can tell this apart from similarly named tools without inspecting their 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 description gives explicit USE WHEN scenarios ('explain what a run will do', 'confirm a Spec is published before talonic_run_spec', 'map field names to keys') and explicit NOT FOR exclusions with named alternatives (talonic_list_specs, talonic_run_spec). This is exactly the when-to-use vs alternative guidance expected.

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?

The description goes beyond the sparse annotations by disclosing the 409 behavior for stale/foreign epochs, the prescribed reaction (stop, discard, re-list), and the auth failure modes with named error codes. It also specifies the lease extension limit relative to sla_deadline_at, which is useful runtime 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?

The description is organized into labeled sections (USE WHEN, NOT FOR, ARGS, AUTH) that are easy to scan and each earns its place. It is dense but free of redundancy, with the most important purpose statement first.

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 tool with no output schema and meaningful auth/error nuance, the description covers when to use it, what it does, how parameters relate to the claim, what errors mean, and how to handle auth failures. Nothing essential for correct invocation 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 schema already documents both parameters well. The description adds practical meaning by saying 'using the epoch from claim' and clarifying that a foreign epoch also returns 409, plus the recovery action. This is a meaningful but not large 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?

The description opens with a specific verb and object ('Extend the lease on a claimed decision task') and adds a hard constraint ('never past its sla_deadline_at'). It also explicitly names sibling tools it is not for, so an agent can distinguish it from claim, submit, release, and fail at a glance.

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 line gives the exact condition for invoking the tool, and the NOT FOR line lists the specific alternative tools for different lifecycle stages. This is explicit routing guidance with no inference required.

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 explains the read-only guarantee beyond the annotations: API-key credentials are restricted to registry tools with `data.read` capability, write-capable tools cannot be invoked this way, and the platform re-checks every call. It also discloses denied-capability error behavior and the shape of the response.

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 longer than average but well-structured with labeled ARGS, USE WHEN, NOT FOR, and RETURNS sections. It is front-loaded with the core behavior and stays focused; minor redundancy in the read-only paragraph keeps it from being maximally concise.

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 dynamic dispatch tool with no output schema, the description covers the API endpoint, credential constraints, argument contract, return shape, optional return fields, and error behavior. An agent has enough information to decide when to use it and how to interpret results.

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 meaningful context: `args` must match the target tool's input_schema, `document_ids` is a hard scope for scope-aware tools, and concrete tool-name examples clarify expected values. This goes slightly beyond the schema without fully duplicating it.

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

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

The description states a specific action: 'Invoke ONE named tool from the platform's agent tool registry directly, with no model in the loop.' It names concrete examples like `query_data` and `get_document_markdown`, and differentiates from the dedicated talonic_* tools by saying those are preferred for their own jobs.

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

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

It gives explicit USE WHEN and NOT FOR guidance: use when `talonic_list_agent_tools` shows `can_invoke: true`, and avoid when a dedicated talonic_* tool already exists. It also tells the agent to pass exactly the `args` declared by the selected tool's `input_schema`.

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

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

Annotations already declare readOnlyHint=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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds value beyond that: the credential-based can_invoke semantics, the read-only nature of the SQL primitives, and the explicit return shape. 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?

Well-structured with USE WHEN / NOT FOR / ARGS / RETURNS sections and front-loaded purpose. Slightly verbose with the enumerated primitive examples, but each section earns its place and improves scannability.

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?

Complete for a registry-listing tool: purpose, usage routing, argument defaults, return format, and credential semantics are all covered. With no output schema present, the RETURNS section is essential and it is provided in detail. Nothing an agent needs 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 parameters (only_invocable, include_schemas) are fully documented in the schema. The description restates them with defaults and meanings, which is redundant but confirms the semantics; baseline 3 is appropriate since 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 (List) and resource (the platform's agent tool registry) with concrete examples of what the registry contains. It distinguishes itself from siblings by explicitly naming talonic_list_fields/talonic_find_data and talonic_search as different discovery surfaces.

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 explicit USE WHEN (capability not covered by talonic_* tools directly, then invoke via talonic_invoke_agent_tool) and NOT FOR (fields/documents discovery) sections, naming exact alternatives. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint and non-destructive behavior, so the bar is lower, but the description still adds substantial context: newest-first ordering, return shape limited to task metadata plus pagination cursor, auth requirements, and the 403 error outcome including the instruction not to retry.

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?

Though longer than typical, every section earns its place: purpose, when to use, when not to use, parameter/return summary, and auth/error handling. The labeled sections make the content scannable and front-load the core 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?

With no output schema, the description tells the agent exactly what will be returned and what won't be. It also covers auth failure modes and provides routing to sibling tools, leaving no obvious gap for an agent 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 coverage is 100%, so the baseline is 3. The description adds useful usage semantics beyond the schema by recommending starting with status 'available' and explaining that cursor comes from pagination.next_cursor, which helps an agent use the parameters correctly.

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 and resource: list one app's decision tasks, newest first. It makes the scope explicit (External-mode, runs parked for an outside agent) and differentiates from sibling tools by referencing talonic_list_agent_tasks and related decision-task tools.

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

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

It gives a clear USE WHEN starting point (status 'available') and an explicit polling-vs-webhook relationship. The NOT FOR section names exact sibling alternatives and sequences them, e.g. claim first, then read the decision package, so an agent knows exactly when to choose other 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 mark the call as readOnly, idempotent, and non-destructive; the description adds meaningful behavioral detail beyond that: default include_superseded behavior, why merged rows are hidden to avoid duplicate ids, and the returned row shape plus cursor pagination. 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 front-loads the purpose and then uses short labeled sections for use conditions, exclusions, args, and returns. Every line earns its place with 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?

Even without an output schema, the RETURNS line supplies the full result field set and describes cursor pagination. Combined with explicit sibling routing and annotation-covered safety, there is no missing context needed to 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 baseline is 3. The ARGS section adds non-redundant guidance by recommending core/proven maturity when building and explaining the duplicate-prevention rationale for include_superseded. It still largely mirrors schema descriptions, so it stops short of a 5.

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 opening sentence uses a specific verb 'List' and a precise object, the workspace Field Registry, and enumerates what each entry contains (stable id, maturity, data type, synonyms, occurrence count). It also distinguishes itself by naming siblings it is not (talonic_search, talonic_filter) and providing use cases for related get_field/field_values 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 USE WHEN block gives concrete scenarios: knowing what data exists before querying it, picking a concept, or needing an exact field id for talonic_get_field / talonic_field_values. The NOT FOR section explicitly points to talonic_search and talonic_filter, so an agent can quickly route among siblings.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: schema_id is a different id from the Spec's, version/materialized_version null means never published, and it reveals the exact returned fields and pagination shape.

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. It packs necessary detail into compact labeled blocks without redundancy, and every sentence earns its place.

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

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

Given there is no output schema, the description fully specifies the return shape including pagination fields. It also covers all parameters, key behavioral nuances, and sibling differentiators, leaving an agent with everything needed to select and invoke the 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?

Input schema has 100% coverage, so baseline is 3. The description adds value by explaining the purpose of each parameter in the context of the tool (e.g., cursor from pagination.next_cursor), and by specifying the order semantics (by updated_at). It does not merely repeat the schema verbatim.

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

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

Description uses a specific verb ('List') and resource ('the workspace's Specs') and immediately clarifies that these are configured pipelines executed by talonic_run_spec. The row-level detail and explicit NOT FOR section distinguish it clearly from sibling tools like talonic_list_schemas and talonic_list_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?

The USE WHEN section explicitly states the conditions for calling this tool, including needing a spec_id for talonic_run_spec or talonic_get_spec. It also names alternatives it is NOT for, giving the agent clear 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?

Annotation Contradiction: the annotations declare readOnlyHint=true, but the description says 'each page read is journaled onto the run,' which is a state change. This directly contradicts the read-only hint. The description is otherwise transparent about auth errors, but the contradiction is severe because it makes the tool's side effects falsely appear harmless.

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 with clear USE WHEN, NOT FOR, ARGS, and AUTH sections, with the core purpose front-loaded. Every section carries necessary operational detail and there is no filler or redundant 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 paginated read tool with no output schema, the description fully compensates: it describes what the page contains, the first page's source document list, the special mining_round package shape, pagination flow, and auth/error behavior. An agent has enough information to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description adds little. The ARGS section restates parameter names without adding new semantic meaning beyond the schema; 'Copy evidence locators verbatim' is a usage note rather than parameter semantics.

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

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

The description states a specific verb and resource: 'Read one page of a claimed decision task's frozen input package' and explicitly distinguishes itself from listing tasks with 'NOT FOR: ... listing tasks (talonic_list_decision_tasks).' This makes the tool's unique purpose immediately clear.

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

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

The description gives explicit usage timing: 'after a successful claim, walking pages from package.first_cursor while pagination.has_more is true.' It also states exclusions (unclaimed tasks, listing tasks) and auth requirements, so the agent knows exactly when and when not to call 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 only signal readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and does so thoroughly: the non-decision release semantics, epoch-bump side effect, HTTP 409 on stale epoch, and detailed auth failure behavior (403 names what is missing, 'tell the user, do not retry'). 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 front-loaded with the core purpose in the first sentence, then organized into scannable labeled sections (USE WHEN, NOT FOR, ARGS, AUTH). Every sentence earns its place given the tool's complex auth and epoch semantics; there is no filler.

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

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

For a mutation tool with complex auth, epoch semantics, and sibling ambiguity, the description covers what it does, when and when-not to use it, parameter behavior, error codes, and authentication requirements. No output schema exists, but for a release action this is adequate. Nothing an agent needs 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 parameters are already documented in the input schema, including the stale-epoch-409 behavior on execution_epoch. The description's 'ARGS: task_id and execution_epoch. Stale epoch is HTTP 409' adds marginal reinforcement but little new meaning beyond what the schema states, 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+resource: 'Release a claimed decision task back to available without deciding it'. It also names the side effect (next claim bumps the epoch) and explicitly distinguishes itself from talonic_fail_decision_task and talonic_heartbeat_decision_task. An agent can select it correctly without opening sibling 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?

Provides an explicit USE WHEN condition (cannot finish within lease/SLA but another claimant could decide) and a NOT FOR clause naming the two alternatives (fail, which raises a review; heartbeat, which keeps the lease). This is model guidance for when and when-not, leaving nothing 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?

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 only indicate readOnlyHint=false and destructiveHint=false. The description adds critical side-effect context: it 'Consumes credits,' ingests file_urls first, returns a RunEnvelope with run_kind that dictates the polling target, and instructs to poll every 5–10s until terminal status. This goes well beyond the structured annotations and fully discloses the asynchronous, credit-consuming 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?

The description is dense but well-organized with clear sections (intro, inputs, USE WHEN, NOT FOR, ARGS, RETURNS). Every sentence earns its place; the core purpose is front-loaded, and the rest is tightly packed without fluff. It's long but justified by the tool's 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?

For a tool with 7 parameters, two input paths, and a non-trivial return/polling contract, the description is remarkably complete. It explains how to obtain spec_id (talonic_list_specs), how to handle new files via the upload flow, the exact return structure, and the polling logic. Nothing an agent needs 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?

While schema coverage is 100%, the description adds meaningful semantics beyond the schema: it emphasizes 'exactly one of document_ids or file_urls,' spells out the limits (1–500 and 1–20), and clarifies that batch_id and metadata are only valid with file_urls. It also explains pipeline_mode ('new' vs 'append' to existing pipeline). This adds real value over 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 opens with a clear verb+resource: 'Run a Spec — the customer's configured pipeline — over documents, in one call.' It explicitly differentiates from siblings by naming what it is NOT for (talonic_extract, talonic_get_run, talonic_get_run_results) and clarifies the two input modes. An agent can immediately grasp the tool's role and scope.

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

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

It provides a dedicated 'USE WHEN' section with concrete user intents (e.g., 'run the invoice pipeline on these documents') and a 'NOT FOR' list that names alternatives. It also gives conditional guidance on choosing document_ids (with the prerequisite upload flow) vs file_urls, and explains the polling flow after the call. This is explicit and actionable.

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

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

Annotations 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?

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the full burden. It discloses transactional verification, state changes on rejection (nothing changes, task stays claimed), stale epoch 409, and detailed auth requirements (tlnc_ key with 'decide' grant, OAuth with apps:decide scope, senior_member role). No contradiction with annotations; this is thorough behavioral disclosure.

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 longer than average but well-organized into clear sections (purpose, USE WHEN, NOT FOR, ARGS, AUTH). Every sentence adds necessary context, and the most critical information (purpose and when to use) is front-loaded. It is structured and free of fluff, though slightly verbose for a single tool description.

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 complex tool with 7 parameters, nested objects, and no output schema, the description covers usage conditions, auth requirements, error codes, and retry behavior. It does not describe the success response format, but that is not essential given the absence of an output schema and the transactional nature described. Overall, it provides sufficient context 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 each parameter is already documented in the input schema. The description repeats key constraints (e.g., outcome must satisfy output_contract, evidence verbatim, [] only if allowed) but adds no new information beyond what the schema descriptions already provide. It does not compensate for any gaps, but none exist, so the baseline 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 the verb 'submit' and the resource 'decision task', explains the platform verifies transactionally and resumes the run, and explicitly differentiates from sibling tools by listing NOT FOR cases with their exact names. This leaves no ambiguity about what the tool does or how it differs from alternatives.

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

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

Provides a dedicated USE WHEN section detailing the conditions (final decision, outcome satisfying output_contract, evidence verbatim, rationale short) and a NOT FOR section naming the two sibling tools to avoid. Also explains error handling (422, 409) and the retry behavior, giving explicit guidance on when to call and when to stop.

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.