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?

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavior: lease expiry semantics, a 409 on conflicting live claim, and the need to persist execution_epoch and lease_expires_at. It doesn't cover retry/idempotency or lease duration, keeping it short of a 5.

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

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

Front-loaded with the action, then structured USE WHEN / NOT FOR blocks and a return-payload note. Slightly dense in the final sentence, but each line carries actionable information.

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

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

With no output schema present, the description compensates by naming the returned fields (input_snapshot, instructions, output_contract) and how to use their Spec rules and enumValues. An agent has everything needed to call and use the result.

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% for the single task_id parameter, so the schema already carries its meaning. The description only indirectly clarifies it by referencing 'Agent-stage task'; baseline 3 applies.

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

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

States a specific verb (claim/reclaim) plus the exact resource and stage (Agent-stage task), and explicitly distinguishes itself from the sibling that only inspects work (talonic_get_agent_task). An agent can select this without opening another schema.

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

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

Has explicit USE WHEN (ready to process a task) and NOT FOR clauses naming two concrete alternatives (talonic_get_agent_task for inspection, talonic_heartbeat_agent_task for lease extension), plus the reclaim-after-expiry condition. 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?

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 only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description goes well beyond by disclosing credit consumption per call, the inclusion of per-field confidence with a <0.7 review threshold, provenance fields, and the cheapest-to-most-expensive source ordering (document_id > file_url > file_data). It also flags the open-capture mode that returns a suggested schema for refinement, which is a non-obvious side effect.

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

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

Front-loaded with the one-line purpose, then segmented by labeled blocks (USE WHEN / NOT FOR / BY NAME / ARGS / COST / RETURNS) that make skimming easy. It is dense and the ARGS block partially restates the JSON Schema's own exclusivity rules, but almost every sentence adds decision-relevant information.

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

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

For an 11-parameter, all-optional tool with nested schema objects, this covers input sourcing, schema selection strategy, cost, and return shape. An output schema exists, yet the brief RETURNS summary (data, confidence, provenance, extraction_id) usefully tells the agent what to check after the call. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by tightening the mutual-exclusivity rules ('define the fields... OR a saved schema_id, not both') and by ranking the document source options by cost. It omits the `file_path` option that the schema documents, and doesn't cover `instructions`, `include_markdown`, or `auto_schema` beyond a passing mention, so it is not fully compensatory.

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

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

States a specific verb and resource ('Extract structured, schema-validated JSON from a document') and enumerates the supported input types (PDF, scan, image, DOCX, email, photo). The 'NOT FOR' line explicitly contrasts it with talonic_to_markdown and talonic_search/talonic_filter, so an agent can route correctly without opening any sibling schema.

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

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

Gives an explicit USE WHEN clause with concrete user phrasings ('turn a PDF into JSON', 'pull fields from a file'), a NOT FOR clause naming the alternatives for plain text and document discovery, and a BY NAME prerequisite workflow (call talonic_search for document_id first). Nearly every routing decision is pre-made for the agent.

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes further by explaining exactly what is destroyed/changed (task ends with status 'failed', a Human Review is raised, the app's fallback policy of rules-decide/hold-for-review/fail-the-run is applied). It also documents stale-epoch behavior (HTTP 409) and the three 403 error codes with explicit 'do not retry' guidance, none of which the annotations carry.

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

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

Front-loaded purpose sentence followed by labeled sections (USE WHEN, NOT FOR, ARGS, AUTH) that let an agent scan for exactly what it needs. Despite covering a lot, every clause carries non-redundant information; nothing is padding.

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

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

With no output schema, the description still tells the agent the observable outcome (Human Review created, fallback policy applied, task status 'failed') and covers the full failure surface: 409 stale epoch and the three 403 codes. Auth requirements (per-app 'decide' grant, apps:decide scope, senior_member tier) are spelled out, leaving no material gap for a mutation tool.

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

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

Schema coverage is 100% and each parameter already documents itself, including the 2,000-character limit on reason and the 409-on-stale-epoch note for execution_epoch. The description restates the three argument names and the character cap but adds no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Report that the claimed decision task cannot be decided') and immediately names the two concrete consequences: raising a Human Review and applying the app's declared fallback policy. It is clearly distinguishable from siblings like talonic_release_decision_task and talonic_submit_decision_task, which are named as the 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?

Explicit USE WHEN condition (package insufficient or contradictory, no claimant could decide) and explicit NOT FOR exclusions that route to named siblings: temporary give-backs go to talonic_release_decision_task, low-confidence decisions go to submit-with-confidence. 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=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?

Goes well beyond the readOnlyHint/destructiveHint annotations: explains least-privilege viewer enforcement for every credential, guarantees write-capable registry tools are never invocable, describes the capability-denied error format, notes server-side re-checking of every call, and sketches return shape (tool, result, citations, artifacts, cards). The idempotentHint=false is the only annotation left unaddressed.

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?

Long but front-loaded and sectioned (USE WHEN / NOT FOR / ARGS / RETURNS). Every sentence carries operational information; nothing is padding, and the critical constraint (read-only for every credential) is bolded near the top.

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?

No output schema exists, so the RETURNS block is necessary and present, including the shape of the nested result and optional citations/artifacts/cards. Combined with the permission model and error behavior, an agent has everything needed to call this correctly on the first attempt.

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 that name must come from talonic_list_agent_tools, that args must match the target tool's input_schema, and that document_ids is a hard scope for scope-aware tools. Most of this restates the schema, but the scope-aware nuance and the external-schema pointer add real value.

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

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

States a specific verb and resource: invoke one named tool from the platform's agent tool registry, with no model in the loop. Concrete examples (query_data, describe_data, get_document_markdown) make the scope unambiguous, and it explicitly positions itself against the dedicated talonic_* 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?

Explicit USE WHEN condition (talonic_list_agent_tools showed can_invoke: true) and an explicit NOT FOR clause directing the agent to prefer dedicated talonic_* tools when one exists. Prerequisite chain and argument contract are both spelled out.

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

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

Annotations already declare this as a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), but the description adds real behavioral context beyond them: a task already taken by another agent returns HTTP 409, metadata-only results are returned, and pagination.next_cursor drives continuation. That is substantive operational detail an agent needs.

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

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

Front-loaded with the core purpose and organized into labeled USE WHEN / NOT FOR / ARGS / RETURNS blocks. The pipeline batching example earns its space by showing a real invocation pattern. 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?

Though there is no output schema, the description compensates by stating RETURNS: metadata only plus pagination.next_cursor, which tells the agent exactly what to expect and how to paginate. Combined with the strong usage guidance, nothing needed to call this 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 limit, cursor, status, and pipeline_id are fully documented in the schema itself, and the description only restates them as 'optional status, pipeline_id, limit, and cursor'. The suggested starting value 'available' adds minor guidance but no new semantic detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List Agent-stage tasks') with a clear scope qualifier ('visible to this Talonic workspace credential'). It is immediately distinguishable from sibling list tools like talonic_list_decision_tasks or talonic_list_specs.

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 name both the conditions for use and the alternative tools (talonic_get_agent_task for payloads, talonic_claim_agent_task for leases). It even describes the concrete workflow (list then claim) and how to handle 409 conflicts.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context: results are filtered by what THIS credential may invoke, the flag defaults govern that filtering, and the response shape (tools[], invocable_count, totalCount) is spelled out. It doesn't mention pagination or any cap on registry size, which is the one behavioral gap for a potentially large listing.

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

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

Front-loaded purpose sentence followed by clearly labeled USE WHEN / NOT FOR / ARGS / RETURNS blocks — very scannable. The parenthetical tool-name list and nested em-dash clauses run slightly long, but each block still carries distinct routing value.

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?

No output schema exists, but the description compensates with an explicit return shape including field names and the invocable/total counts. Combined with the documented args, defaults, and the downstream invoke tool, an agent has everything needed to call this and act on the result.

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, and the description goes further by giving both booleans with their defaults and the intent behind them ('hide tools this credential cannot run', 'include each tool's JSON input schema'). Nothing about consequences or interaction between the two flags (e.g. that schemas for non-invocable tools are hidden) is stated, keeping it below 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?

Specific verb and resource ('List the platform's agent tool registry'), with an enumeration of what's in the registry (find_data, describe_data, query_data, get_document_markdown, workspace_overview) and the per-credential invocability flag. The NOT FOR line explicitly separates it from the sibling listing tools (talonic_list_fields, talonic_find_data, talonic_search), so an agent can route without opening a schema.

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

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

USE WHEN names the exact trigger (a capability the talonic_* tools don't cover) and even closes the loop by pointing at talonic_invoke_agent_tool as the follow-up call. NOT FOR names three concrete alternatives with the reason ('those are shaped for you'), 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?

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?

Annotations declare readOnlyHint=false and destructiveHint=false but say nothing about the workflow. The description supplies the missing behavioral layer: the link is user-opened (out-of-band), an id is pre-allocated, the link expires, and the caller must poll talonic_get_document until 'completed' before calling talonic_extract. It even enumerates terminal failure states (ocr_failed, extraction_failed, error) and instructs the agent to stop polling — genuinely actionable context not present in the structured fields.

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

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

Front-loaded with the core action and return shape, then cleanly segmented into USE WHEN / NOT FOR / ARGS / RETURNS. Every sentence carries distinct information — no restatement of the name or filler.

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

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

Although an output schema exists, the description goes beyond it to explain the multi-step human-in-the-loop protocol (poll, then extract, with exit conditions on failure), which is exactly the orchestration knowledge an agent needs and structured fields cannot convey.

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 parameter's own description already covers extension and MIME-type inference. The 'ARGS: filename (with extension)' line adds a light reinforcement of the extension requirement but nothing the schema doesn't already state, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a browser upload link... to add a file to their workspace') and immediately names what it returns (link + pre-allocated document_id). This is clearly distinguishable from siblings like talonic_extract (URL-based ingestion) and talonic_get_document (status polling).

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 clause defines the trigger condition (client cannot attach file bytes, or file too large for tool arguments). NOT FOR clause names two concrete alternatives and routes to them (existing document → document_id; public file → file_url on talonic_extract). Both when and when-not are covered.

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?

Annotations only state readOnly=false/destructive=false, so the description carries most of the burden and does add real value: transactional all-or-nothing validation before writing, and the parked-document resume transition. It stops short of describing rejection/failure behavior (e.g. whether the lease survives a validation failure) beyond what the schema already covers for stale epochs and quotes.

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

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

Three tightly labeled blocks (statement, USE WHEN/NOT FOR, ARGS) with the state-changing effect front-loaded. Every sentence carries distinct information; nothing is repeated from the schema verbatim.

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 a nested outputs object, transactional semantics and the resume effect are covered. There is no output schema, yet the description does not indicate what a successful submission returns (e.g. updated field values or status), which is the one remaining gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a non-obvious constraint: outputs must be keyed exactly by declared field key. It also names the argument set (task_id, execution_epoch, outputs, optional summary), giving useful orientation ahead of opening the schema.

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

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

States a specific verb+resource ('Submit declared output fields for a claimed Agent-stage task') plus the side effect ('resume the parked document'). It is clearly distinguishable from sibling claim/heartbeat/decision-task tools by naming the Agent-stage task lifecycle and the declared-field contract.

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

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

Explicit USE WHEN condition (processing complete, every required output in output_contract ready) and explicit NOT FOR exclusions (undeclared fields, partial lease maintenance) with the correct alternative named: talonic_heartbeat_agent_task. 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?

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.