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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation status is covered. The description adds nothing about behavior: no indication of whether duplicate identifiers are rejected, what happens to an existing primary when is_primary=true, or permission/auth requirements. For a write tool it leaves the agent guessing.

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

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

A single, front-loaded sentence with no filler; the verb and resource lead, and the examples are compact. Nothing to trim.

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 and only mutation-safety annotations, the description should carry behavior and usage context for a 5-parameter write tool, but it does not. It is adequate to identify the operation against a fully documented schema, but side effects, duplicate handling, and the primary-identifier interaction are unaddressed.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, including the enum for type and examples for value. The description's parenthetical list of identifier types merely restates the enum, adding no new semantic detail. Baseline 3 applies.

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

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

The description states a specific verb (Add) and resource (an identifier) and scopes it to an animal, then enumerates the five identifier categories. It is clearly distinct from add_premises_identifier, but it does not name any sibling or clarify against list_identifiers/find_animal_by_identifier, keeping it short of a 5.

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

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

No guidance on when to use this versus remove_identifier, find_animal_by_identifier, or find_or_create_animal_by_eid. There are no stated prerequisites, no mention of farm scoping, and no exclusions.

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

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

Annotations cover only safety (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context beyond that: values are stored as strings with leading zeros preserved, no registry verification is claimed, and OTHER scheme requires a scheme_label. Useful transparency for a mutation tool, though it says nothing about permissions or duplicate handling.

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 short, front-loaded sentences with no filler. The core action leads and the constraints follow, though the storage/verification notes could be tightened.

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 10-parameter mutation tool with 0% schema coverage and no output schema, the description is thin. It documents a couple of behaviors and one validation rule but leaves most parameter meaning and any return/permission context unaddressed.

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 0%, so the description must carry the full param burden, but it only touches 'value' (string, leading zeros) and 'scheme'/'scheme_label'. The required location_id and seven optional params (issuer, source, farm_id, confirmed, is_preferred, jurisdiction) are left entirely unexplained.

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+resource+scope: adds a premises identifier to a root premises. An agent can distinguish it from add_identifier (animal identifiers) and update_premises_identifier by the 'add to a root premises' framing, though it does not name any sibling explicitly.

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

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

Usage is implied by the operation name (creating a new premises identifier vs updating one), and one concrete rule is given ('Scheme OTHER needs a scheme_label'). However, no explicit when-to-use/when-not or pointer to update_premises_identifier/delete_premises_identifier is provided.

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

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

Annotations already declare destructiveHint=true, so the write profile is known. The description adds genuinely new behavior beyond that: cascade semantics (archiving a premises also archives sublocations), the side effect on a matching home default, and the retention rule that history keeps the site while it disappears from new selections.

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 short sentences, zero filler, front-loaded with the action and then layered with cascade and retention facts. 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?

For a destructive mutation with no output schema and no annotation-supplied parameter help, the description covers behavior well but omits how to reverse the action (restore_location is a sibling) and says nothing about the version/farm parameters. Adequate, with clear 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 description coverage is 0%, so the description must carry parameter meaning, and it does not mention any of the three parameters by name. farm_id and especially expected_version (an optimistic-concurrency control) are left entirely unexplained, and only 'a location' loosely gestures at location_id.

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 ('Archive a location') and immediately scopes the operation, so the agent can distinguish it from update_location or restore_location. It stops short of naming a sibling, so the differentiation is implied rather than explicit.

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

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

No explicit when-to-use or when-not-to-use guidance. The clause 'History keeps the site; it is excluded from new selections' implies this is a soft-delete/retire operation rather than a hard removal, which is useful context, but the description never points to restore_location as the undo path or states prerequisites.

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 annotations (readOnly=false, idempotent=true, destructive=false) by disclosing atomicity of the write, the semantics of approval attestations (they bind reviewed inputs but do not prove a human reviewed them), and the no-substitution/fresh-preview rule. This is exactly the mutation context 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?

Dense but front-loaded, leading with the core action before the gating rules and recovery guidance. Every sentence carries load, though the attestation aside and recovery clause make it longer than strictly minimal.

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, and the description doesn't need to explain return values, but for an atomic commit tool it covers inputs, preconditions, and failure recovery thoroughly. A brief note on what a successful commit produces would close the 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 only 33% and the approval object is nested, yet the description adds real meaning: preview_id alone is insufficient, confirmed must be true, and preview_hash must equal the hash of the exact preview the human reviewed. It does not cover farm_id (left to the schema) and gives no format example for the hash beyond the schema pattern.

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 ('Save one approved workflow preview') and names the mechanism ('atomic birth writer'), and implicitly distinguishes itself from preview_workflow/get_workflow_preview by insisting on approval + preview_hash rather than a preview id. It never explicitly names a sibling as the alternative operation, so it stops short of a 5.

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

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

Explicit preconditions (approval.confirmed true and the exact reviewed preview_hash; a bare preview id is insufficient), an exclusion ('accepts no replacement inputs; a changed payload or relevant state requires a fresh preview'), and a recovery alternative ('read get_workflow_preview first'). When/when-not/alternative routing is all present.

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 annotations (idempotentHint, destructiveHint=false) by explaining the retry contract: 'An unchanged retry of the exact approved tuple returns the already-saved event; it is a retrieval, not a correction.' It also states the hash must never be generated and that uncertain outcomes must be reconciled with reads before further writes. This is exactly the mutation-safety context the annotations cannot carry.

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

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

Front-loaded with the core action and the approval precondition, then the hash/retry rules, then the amendment route and fallback. Dense but every sentence carries an actionable constraint; nothing is decorative, though the block is long enough to be slightly heavy for a single call.

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 nested-bundle write with no output schema, the description supplies the lifecycle context (preview → confirm → amend), the idempotency behavior, and the failure fallback. It leaves farm_id semantics unstated and return shape undefined, but the agent has enough to invoke it correctly.

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

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

Schema description coverage is only 25%, so the description must compensate, and it does for the critical parameters: preserve request_id, bundle, and confirmation_hash exactly and never generate the hash. farm_id is left unaddressed, but the high-risk tuple semantics are made explicit.

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: 'Save one complete producer-approved birth bundle.' It clearly distinguishes itself from preview_birth_event by requiring the producer to have approved the exact preview, and from the amendment route (preview_workflow/commit_workflow). An agent can tell exactly what this does without opening the schema.

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

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

Explicit precondition ('Only call after the producer explicitly approves the exact preview'), a named alternative for corrections ('use preview_workflow with operation amend_birth ... then review and commit_workflow'), an explicit prohibition ('Do not re-record one or use generic edits as a workaround'), and a fallback path ('otherwise stop and contact ... support'). Both when-to-use and when-not-to-use 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 declare readOnlyHint=false and destructiveHint=false, leaving behavior largely to the description, which delivers: writes are append-only revisions (not in-place mutation), projections rebuild atomically, and optimistic concurrency via expected_revision. It doesn't clarify reversibility of the new revision or return content, but it goes well 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?

Two tightly packed sentences with no filler; the core (append full replacement revision, atomic rebuild) is front-loaded before the concurrency/idempotency caveats.

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 write tool with no output schema, 0% schema coverage, and a nested payload object, the description covers the tricky concurrency contract but omits payload shape, what the call returns (new revision? updated event?), and permission/auth needs. Adequate but with clear 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 description coverage is 0% across 7 parameters, so the description carries the full burden. It explains expected_revision and request_key semantics well, but leaves event_id, reason, source, farm_id, and the nested payload object completely undocumented.

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

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

Names a specific verb (correct) and resource (traceability event) plus the mechanism: 'append a full replacement revision' with atomic projection rebuild. This distinguishes it implicitly from create_traceability_event and void_traceability_event, though it doesn't name those siblings directly.

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

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

The description explains the concurrency guard (expected_revision against stale edits) and idempotency behavior (mismatched request_key body conflicts), which frames when this call is safe/failing. However, it never states when to pick this over void_traceability_event or create_traceability_event, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered and the description is consistent with it. Beyond that, the description adds no behavioral context: nothing about duplicate-name handling, what the default farm behavior is, or what the call returns for a 10-parameter write.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though it is so terse that it provides no structure for a tool with 10 parameters and a nested metadata object.

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 10-parameter creation tool with no output schema and a nested metadata object, the description is inadequate: it says nothing about defaults (farm_id optional via default, inventory_status defaulting to CURRENT), duplicate handling, or the result of creation. It leaves the agent to infer everything from the schema.

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

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

Schema description coverage is 100%, so all 10 parameters (including the birth_date and inventory_status nuances) are already fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description names a specific verb and resource ("Create a new animal record") and the farm scope, so an agent can tell it produces a new animal entity. However, it does not distinguish itself from the sibling find_or_create_animal_by_eid, which is an alternative creation path, nor from update_animal/delete_animal.

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

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

There is no when-to-use or when-not-to-use guidance. The description never mentions that find_or_create_animal_by_eid is the preferred route when an EID is known, nor any prerequisite such as a default farm being set.

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; the description adds the crucial behavioral fact that this creates a proposal and 'never records any data by itself', plus the explicit confirmation step at the chute. That is exactly the kind of lifecycle detail an agent needs and cannot get from 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?

The purpose and the never-records-data caveat are front-loaded, and the remaining sentences are information-dense rather than redundant. It is a single long block that could be broken into clearer segments, but nearly every clause carries actionable constraint content.

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

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

For a six-parameter creation tool with no output schema, the description covers the mutation lifecycle, the widget vocabulary, ordering rules, and the EID exclusion, which is everything an agent needs to build a valid payload. No obvious gap remains.

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 the free-form `options` object and widget `type` enum are only meaningful with the description's catalog: weight uses options.unit, score uses options.min/max with BCS 1-5 defaults, select uses options.choices, treatment uses options.presets, boolean is a yes/no tap. It also supplies arrangement and size ('full'/'half') conventions and a ~6 widget cap that the schema does not encode.

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 first sentence gives a specific verb and resource ('Propose a chute-mode work session') plus the input modality ('from a description of the day's work'), and the second sentence sharpens the scope by clarifying it produces only a PROPOSED session. This clearly separates it from siblings like list_chute_sessions, get_chute_session, and update_chute_session.

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 states the workflow context clearly: propose here, then the user reviews, edits, and starts at the chute. It also gives inclusion guidance ('never add a widget for EID scanning') and a sizing heuristic. It stops short of naming a sibling or stating explicit when-not-to-use conditions, so it is clear context without full routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds nothing beyond that: no mention of name uniqueness, duplicate handling, permission requirements, or what happens when farm_id is omitted and no default is set.

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

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

A single short sentence with no filler or repetition, and the verb-resource core is front-loaded. It is efficient, though its brevity borders on under-specification rather than tight conciseness.

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

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

For a simple creation tool with one required parameter, full schema coverage, and annotations, the definition is adequate but thin. Missing are the details an agent would want before acting: uniqueness constraints on the group name, default-farm resolution behavior, and expected outcome on success.

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

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

Schema description coverage is 100%, so all three parameters (name, farm_id, description) are documented in the schema itself. The description adds no syntax, format, or constraint detail beyond what the schema already provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'Create a new group'. It is immediately clear what the tool does, though it does nothing to distinguish itself from siblings like create_record, create_location, or create_animal, which follow the same verb pattern.

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

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

No guidance on when to use this versus the surrounding group tools (list_groups, get_group, update_group, delete_group, restore_group). The 'on the farm' phrasing hints at farm scoping but never explains the relationship to farm_id or when a group already exists.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful hierarchy behavior (root vs child location), but says nothing about permissions, side effects on parent records, or whether duplicates are rejected. Adequate but not rich.

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

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

Three short sentences, front-loaded with the core action and then the parent_id decision rule. Nothing is padded, though the phrasing could be marginally tighter.

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

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

For a 9-parameter creation tool with 11% schema coverage and no output schema, the description should carry far more weight. It covers only the one required parameter and parent_id, leaving the majority of optional fields unexplained and giving no hint of the returned location or identifiers.

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 only 11% across 9 parameters, so the description must compensate and largely does not. It explains parent_id (which the schema already documents) and confirms name is sufficient, but address, context, country, farm_id, category, province_state, and legal_land_description get no meaning from either source.

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 ('Create a location') and immediately clarifies the two creation modes (root premises vs sublocation), which is genuinely differentiating. It does not distinguish itself from siblings like update_location, archive_location, or restore_location, so it stops short of a 5.

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

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

Gives clear conditional guidance: omit parent_id for a premises, set it to an existing premises for a field/pen/barn/sublocation, and notes that name alone is sufficient for a valid call. No exclusion guidance or alternatives (e.g., update_location) are named, so it is clear context without full routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description contributes 'immutable' and 'producer-approved', which are real behavioral facts beyond the annotations, but it does not explain the idempotency semantics (e.g. what happens when same name/version is resubmitted) or any authorization requirement.

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

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

Two short sentences, zero filler, with the action and the immutable/producer-approved constraint front-loaded. Nothing is redundant and nothing needs trimming.

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 4-parameter mutation tool with no output schema and 0% schema description coverage, the description covers the core action and one important behavioral fact (immutability) but leaves farm_id, uniqueness/idempotency behavior, and the response shape unaddressed. Adequate but with clear 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 description coverage is 0%, so the description must carry parameter meaning, and it only partially does. 'The exact named steps provided' maps loosely to the steps array, and 'name'/'version' are implied by 'protocol version', but farm_id is never mentioned and no format, length, or ordering guidance is added.

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 (create a farm protocol version) and adds meaningful qualifiers: producer-approved, immutable, built from exact named steps. An agent can tell what is produced without opening the schema. It does not, however, reference the available sibling list_protocol_versions or otherwise differentiate itself from the workflow-template 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 sentence 'Do not invent or prescribe care steps' is an input-authoring constraint rather than routing guidance. There is no statement of when to create a protocol version versus listing existing ones, what prerequisites exist, or what happens on duplicate name/version. An agent gets a constraint but no usage 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 tell the agent this is a non-read-only, non-destructive write. The description adds genuinely non-obvious behavior: assignments are created INACTIVE and require in-app Rations-page activation before appearing on the Feed Mode Today board. That is exactly the kind of side-effect context structured fields do not carry.

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

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

Three sentences, front-loaded: purpose first, hard constraints second, lifecycle behavior third. No redundant restatement of the title or schema, and every clause 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?

For a 5-parameter mutation tool with no output schema, the description covers the identity of the resource, the boundaries of agent behavior, and the activation lifecycle. 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 description coverage is 100%, so the baseline is 3 and the schema already documents each parameter including nested assignments. The description adds marginal framing (whole object is a 'per-head-per-day pounds' recipe, group assignment is optional) that ties the parameters to the domain, but no new syntax beyond the schema.

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

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

States a specific verb (create) and resource (feed ration) with the exact shape of the object ('a named recipe in per-head-per-day pounds, optionally assigned to groups'). This is clearly distinguishable from the read siblings list_rations/get_ration, and the domain framing (a 'recipe') removes ambiguity.

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

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

Explicitly names the trigger condition ('a feed ration the user has already decided on') and the negative case ('never formulate, balance, or validate... if asked what or how much to feed, decline and refer the user to their nutritionist'). This is textbook when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds genuine non-annotation context: that an unattached record will not appear in any animal's history, and that producer-supplied facts, unknowns and attachments should be preserved. It does not mention permissions or how farm_id defaults, so it stops 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?

The core purpose and the attachment constraint are front-loaded and the breeding-vs-birth example is a well-placed disambiguator. Slightly verbose: the clause about 'preserving the producer's facts, unknowns and attachments' is abstract and costs a sentence without adding actionable detail.

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 7-parameter, no-output-schema write tool, the description supplies the routing rules, the attachment precondition, and the failure mode of omitting attachments, which is enough to call it correctly. It leaves minor gaps such as whether farm_id falls back to a default farm and what the call returns, but nothing blocking.

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 would be 3, but the description adds two things the schema does not: the semantic mapping of the type enum (GENETIC for turnout/mating/breeding/exposure) and the requirement that animal_ids/group_ids be non-empty despite both defaulting to []. The 'resolved UUID' phrasing also signals IDs must be looked up first.

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

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

States a specific verb ('create') plus the resource ('a record') and enumerates the concrete event kinds it covers (feeding, health treatment, movement, turnout/mating/breeding/exposure). It goes further than the name by clarifying that a breeding-type observation is a record rather than a birth event, which cleanly separates this tool from the propose_birth_event/preview_birth_event/confirm_birth_event 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 routing guidance: genetic/breeding observations go here with type GENETIC while 'a ewe lambing twins is a propose_birth_event bundle', naming the alternative and the condition that selects it. It also states a hard precondition ('Always pass at least one resolved animal or group UUID') and the consequence of ignoring it.

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 tell the agent this is a non-destructive write. The description adds genuinely useful context beyond that: the event must be 'reviewed', payload structures are authoritative, and the request_key provides idempotent retry with identical retries replaying. It stops short of describing the response or any side effects on animal/inventory state.

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

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

Three dense sentences, front-loaded with the verb and typed-kinds list, then payload guidance, then the idempotency prerequisite. Every sentence carries information, though the middle sentence packs several distinct facts and the parenthetical kind list is long.

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 payload object, no output schema, and partial schema descriptions, the definition covers the shape of the input, the tolerance for incomplete facts, and the idempotency contract. What it omits — permission requirements and what the call returns — matters but is narrow given the payload guidance provided.

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 50% and the text compensates well: it explains the canonical payload contents (populations, optional movement/identification facts, explicit inventory effects, links) and gives the request_key its semantic role of idempotent replay. The bare source/farm_id properties remain unexplained, keeping it below 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?

States a specific verb ('Create') plus a typed resource and enumerates the nine event kinds (movement, purchase, sale, import, export, death, slaughter, disposal, identification), so an agent knows exactly what artefact is produced. It does not, however, distinguish this from siblings like correct_traceability_event or void_traceability_event, which also target traceability events.

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

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

Usage is implied by the enumerated kinds and the note that structures are authoritative but incomplete facts are allowed, which hints at what input is acceptable. There is no explicit when-to-use vs when-not-to-use routing against the correction/void siblings, and no stated prerequisites (permissions, prior review step) beyond the request_key requirement.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description's job is to add context. It does: OWNER-role authorization, the version-1 side effect, and an integrity constraint warning against fabricating a definition. Good added value without contradicting 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?

Three short sentences, core action front-loaded, each one adding a distinct fact (scope, permission, publishing boundary, integrity rule). Zero 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 deeply nested, effectively undocumented 'definition' payload and no output schema, the description covers permissions and the publishing boundary but says almost nothing about how to construct the definition or what is returned. Adequate at the edges, thin where the tool is actually complex.

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 only 33% (farm_id is documented; definition and is_default are not), so the description carries the burden and largely fails. The one hint – 'never invent a definition the producer did not confirm' – is a content-integrity caution, not an explanation of the required nested definition payload or the is_default flag.

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 + resource ('Create a farm-owned workflow template'), plus the notable scope detail that it also creates version 1. It draws an explicit boundary against publish_workflow_template_version by stating publishing is a separate operation, so an agent can place it among its siblings 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?

States a hard prerequisite ('Requires the OWNER role') and clarifies that publishing is not part of this call, which routes the agent to the right sibling. No explicit when-not-to-use cases beyond that boundary, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. 'Soft delete' does add genuine behavioral value by implying data is retained rather than destroyed, but the description omits cascade effects (identifiers, traceability events, group membership) and any permission or restore-path information.

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

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

A single short sentence with the verb and resource front-loaded and no filler. Appropriately sized for the operation it names.

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

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

For a destructive mutation with no output schema, the description should explain the consequences of a soft delete: whether the animal disappears from list_animals/get_animal, what related records are affected, and whether recovery is possible. None of this is present, leaving significant operational 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 description coverage is 100%, so both parameters (animal_id, farm_id) are already documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb ('delete') and resource ('an animal record'), and the parenthetical 'soft delete' sharpens the operation's nature. It does not explicitly contrast itself with siblings such as update_animal or delete_record, but the resource is unambiguous enough to route correctly.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative is named. Notably, sibling tools include restore_group and restore_location for their delete counterparts, but no restore_animal exists — the agent gets no signal about whether a soft delete here is recoverable or what the intended trigger is.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered structurally. The description adds genuinely useful context beyond that: the operation is a soft delete, the group leaves the active list, and it is reversible via restore.

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

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

Two short sentences with zero filler, and the crucial semantic qualifier ('soft delete') is front-loaded rather than buried.

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 mutation with no output schema, the description covers the essential behavioral facts an agent needs: it is reversible and affects visibility. It stops short of stating permission requirements or explicitly pointing at the restore counterpart.

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

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

Schema description coverage is 100%, so both group_id and the optional farm_id are already documented in the schema. The description adds no parameter-level detail (e.g., default-farm resolution behavior), so the baseline 3 applies.

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

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

States a specific verb and resource ('Archive (soft delete) a group') and immediately clarifies the actual semantics, which differs from what the name 'delete' implies. An agent can distinguish this from a hard-delete or from restore_group without opening the schema.

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

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

Usage is implied by the semantics: use this to hide a group while keeping it restorable. However, it never explicitly says when to prefer this over a true delete, nor does it name restore_group as the paired recovery tool, leaving the routing 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=false and destructiveHint=true, so the safety profile is covered. The description adds only that the target is a premises identifier on a root premises and does not disclose reversibility, permissions, or side effects beyond what the annotations already state.

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

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

A single front-loaded sentence with the destructive verb first and zero filler. It is well structured and appropriately sized, though its brevity comes at the cost of the missing detail noted elsewhere.

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

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

For a destructive mutation with three parameters at 0% schema coverage and no output schema, the description is too thin. It should at least identify the affected parameters or state the scope of the removal, but an agent cannot call this correctly from the text alone.

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 0%, and the description names no parameters. It alludes to entities ('premises identifier', 'root premises') that vaguely map to identifier_id and location_id/farm_id, but it clarifies neither their format, their optionality, nor the role of farm_id.

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 ('Remove') and resource ('premises identifier from a root premises'), which lets an agent distinguish it from add_premises_identifier and update_premises_identifier. It does not explicitly name a sibling, but the scope is clear enough to place the tool.

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

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

There is no when-to-use, when-not-to-use, or prerequisite guidance. Nothing tells the agent how this differs from remove_identifier (animal identifiers) or when a premises identifier should be detached, so the routing burden is entirely on the name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description's 'soft delete' is genuinely additive — it tells the agent data is likely recoverable rather than purged — but it goes no further: no cascade effects, permission requirements, or recovery path are described.

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

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

A single short sentence with the verb front-loaded and the key qualifier ('soft delete') placed immediately after it. Nothing is padded or repeated from 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?

For a low-complexity mutation with two params, one required, no nested objects, and no output schema, this covers the essentials. It still omits the consequences of the soft delete (recoverability, side effects, whether dependent data is affected), which matters for a destructive 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?

Schema description coverage is 100%, so both record_id and farm_id are already documented, including the optional/default behavior of farm_id. The description adds no syntax, format, or edge-case detail beyond what the schema provides, which is the baseline expectation here.

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 ('Delete... a record') and the parenthetical '(soft delete)' immediately clarifies the kind of deletion. It is clear enough to act on, but it does nothing to distinguish itself from the many other delete_* siblings in this namespace (delete_animal, delete_group, delete_premises_identifier).

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as restoring a soft-deleted record or where the record goes after deletion. The agent must infer all routing from the name alone.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real value beyond them: it discloses that no livestock/domain data is written, and it imposes an ownership/authorization requirement not visible anywhere in the schema. The "read-only scope but not a read" phrasing is awkward but consistent with readOnlyHint=false rather than contradicting it. It omits what state the preview is left in afterward.

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

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

Two short sentences, action front-loaded, no filler. Minor deduction for the telegraphic "without livestock writes" and the internally puzzling "Read-only scope but not a read," which cost a beat of parsing.

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 state-mutating tool with no output schema and half its parameters undocumented, the description covers the ownership prerequisite and the mutation boundary well. It does not say what happens to the preview after invalidation (retrievable? error on later use?) or confirm idempotent re-invocation behavior, leaving an agent to guess at the post-condition.

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 only 50% – preview_id, the single required parameter, has no schema description – and the description does not compensate, saying nothing about what preview_id identifies or what farm_id does. The only relevant hint is the owner constraint, which describes the actor rather than either parameter.

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?

"Invalidate an uncommitted preview" gives a specific verb plus resource, and the phrase "uncommitted preview" situates it in the preview→commit lifecycle alongside preview_workflow/commit_workflow. It never names those siblings, so differentiation is inferable rather than explicit.

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

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

The prerequisite ("the requesting actor must be the preview owner") is stated, which is genuinely useful context for deciding whether the call will succeed. However, it never says when to discard versus when to commit or leave the preview alone, so the when-to-use decision is left implicit.

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

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

The description adds substantial behavioral context beyond the annotations: approval requirements for create/cancel/download, the fact that download writes a ZIP on the MCP host rather than the user's chat machine, and privacy exclusions. These are exactly the operational details an agent needs before invoking the tool.

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

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

The description is dense and front-loaded, starting with the resource and then summarizing each operation and its constraints in a compact sequence. Every sentence provides actionable information with no filler.

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

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

For a multi-operation tool with four parameters and no output schema, the description omits which parameters apply to which operations and does not describe return values. It covers operation behavior well, but an agent would still need to guess at parameter-to-operation mapping.

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 0%, so the description must carry parameter meaning. It explains `output_path` for download and the operation values, but it leaves `farm_id` and `export_id` completely undocumented, so the compensation is only partial.

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 the resource as 'Farm archive operations' and then enumerates what each operation does. It is clear enough for an agent to understand this is a multi-operation archive tool, but it does not explicitly differentiate itself from any sibling tool.

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 classifies `list` and `status` as reads and explains that `create`, `cancel`, and `download` have approval requirements. This gives useful context for selecting an operation, but it does not state when to use this tool instead of alternatives or when not to use it.

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, and the description adds genuinely new behavioral context: it creates an animal when no match exists, and it is deprecated. That create-on-miss side effect is the key trait an agent must know. It stops short of describing return format or failure modes, so not a 5.

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

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

Three sentences, each earning its place: deprecation status front-loaded, behavioral warning, then routing. No filler and the most decision-relevant information (deprecated, write-capable, use alternatives) leads.

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 deprecated, mutation-disguised-as-lookup tool, the definition covers status, side effect, and routing completely. No output schema exists, so return values need not be explained, and nothing an agent needs to call this safely 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% across both parameters, so the schema already documents 'eid' and 'farm_id'. The description adds only the EID expansion ('Electronic ID'), which is marginal. Baseline 3 is appropriate when the schema carries the 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?

States a specific verb and resource ('Find or create an animal by EID') and explicitly frames itself as a write-capable lookup rather than the read-only sibling. It contrasts itself against both 'lookup_animal_by_eid' and 'find_or_create_animal_by_eid', so an agent can distinguish it from siblings 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?

Gives explicit exclusions ('Never call it for a read-only identifier lookup') and names the correct alternative for each case ('lookup_animal_by_eid' for reads, 'find_or_create_animal_by_eid' for intentional creation). This is exactly the when/when-not/alternative structure that routing requires.

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 supply readOnlyHint=true, so the description carries the rest and does add real behavior: include_historical surfaces superseded and void facts, and omitting type returns candidates instead of guessing. That is valuable non-obvious semantics. It still omits return shape, scoping, and pagination.

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

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

Two dense sentences with the core lookup behavior front-loaded and parameter effects second. No filler, though phrases like 'returns candidates rather than guessing' are slightly cryptic for the space they occupy.

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 4-parameter read tool with no output schema and zero schema coverage, the description covers the search semantics but leaves farm_id meaning, candidate result shape, and any result limits unaddressed. Adequate for the core action, incomplete around the edges.

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 0%, so the description must compensate for all four parameters. It meaningfully explains type ('typed'), value ('string value'), and include_historical (superseded/void facts), but says nothing about farm_id scoping or the 50/128 length limits, leaving one parameter fully undocumented.

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: 'look up typed identifier observations by string value across event revisions.' That is concrete and distinguishes it from simple identifier lookups by emphasizing revision-spanning history. It stops short of naming the obvious sibling alternatives (find_animal_by_identifier, lookup_animal_by_eid), so an agent must infer the boundary.

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 implies when the tool is useful (recovering superseded/void facts via include_historical) and notes that an untyped search yields candidates, but it never explicitly contrasts this with find_animal_by_identifier or list_identifiers. Usage context is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write surface is known. The description adds meaningful context beyond that: it creates on no-match, requires Editor access, and warns of explicit-intent gating. It does not state what is returned (found vs newly created) or idempotency behavior, 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?

Three short sentences, front-loaded with the operation and its side effect, followed by prerequisites and the alternative. 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 no-output-schema, two-param tool with annotations covering safety, the description covers purpose, side effect, prerequisite, and sibling disambiguation. Only the return semantics (whether the existing animal or the new one is returned) are absent, a minor 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 both parameters (eid, farm_id) are already documented in the schema. The description only reinforces the EID lookup concept and adds no syntax, format, or default-farm nuance beyond the schema baseline.

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

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

States a specific verb+resource (find or create an animal by EID) and immediately clarifies the dual nature of the operation. Names the sibling read tool it must not be confused with, so an agent can differentiate without opening 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?

Explicitly states when-to-use (when intent to create inventory exists), the prerequisite (Editor access), and the alternative ('Use lookup_animal_by_eid for reads'). Clear routing 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?

Annotations already declare readOnlyHint=true, so safety is covered. Beyond that, the description discloses pagination behavior ('page with birth_skip while has_more is true') and the non-obvious edge case that saved birth bundles are returned even when no ordinary records exist, which is real behavioral value.

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

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

Two dense sentences with no filler, front-loaded with the primary action. The paging clause is somewhat compressed but still readable.

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

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

There is no output schema, so the description carries some burden of describing returns. It hints at saved_births and has_more but says nothing about the shape of the core animal payload or what happens when include_saved_births is false, leaving a modest gap for a no-output-schema tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains why include_saved_births matters (bundles returned despite no ordinary records) and ties birth_skip to the has_more loop. birth_take and farm_id are left to the schema.

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

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

States a specific verb and resource ('Get an animal by UUID'), which is more precise than the tautological title. However, it never distinguishes itself from nearby siblings like lookup_animal_by_eid or find_animal_by_identifier, leaving the agent to infer that this one requires an internal UUID.

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

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

The description implies usage ('by UUID') and gives operational guidance for the saved-births paging case, but names no alternatives and gives no explicit when-not-to-use condition. An agent has to infer the UUID-vs-EID routing itself.

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=false, so the safety profile is covered structurally. The description adds one genuinely useful behavioral fact — results are permission-scoped to what the current user may access — but says nothing about not-found behavior, what the 'evidence' payload contains, or whether omission is silent.

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

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

A single tight sentence with no padding, and the core action is front-loaded. It is efficient but borders on under-specified rather than maximally useful.

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 full responsibility for describing the return shape, yet 'and evidence' is undefined — an agent cannot know what fields come back or how evidence is structured. Combined with 0% parameter coverage and no failure-mode guidance, the definition is too thin for a retrieval tool that returns a composite object.

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 0%, so the description must carry the burden for both parameters. It never mentions event_id (the required key) or explains the optional farm_id — an agent cannot tell from the text whether farm_id is a scope filter, a default context, or required when the event belongs to multiple farms.

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?

Uses a specific verb ('Retrieve') with a specific resource ('a saved birth event and evidence'), which is enough to distinguish it from list_birth_events and from the preview_/confirm_ pair. It stops short of explicitly differentiating it from get_birth_history_evidence or get_birth_source_evidence, so it is clear but not fully disambiguated among 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 gives no guidance on when to use this tool versus list_birth_events, preview_birth_event, or the other birth-evidence tools. The only usage-ish signal is 'the current user may access', which gestures at access scoping without stating any prerequisite or exclusion.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: presumed sire evidence is a review proposal and never DNA confirmation or an automatic parentage write, which tells the agent the returned data is advisory and has no side effect on parentage. It stops short of noting pagination or result size.

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

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

Two sentences, no filler, and the scoping information leads. The second sentence is slightly dense and the 'review proposal / never DNA confirmation' clause could be tighter, but every sentence carries weight.

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 evidence tool with annotations covering safety and no output schema, the description adequately frames both what is read and the interpretive status of the sire evidence. Missing only secondary details like result volume or ordering.

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 only 33% (farm_id is the sole documented parameter). The description implies dam and birth-date scoping ('for a dam/birth date'), which maps to the required params, but adds no format or constraint detail beyond the schema's uuid and date patterns. Adequate but not compensating for the coverage gap.

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

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

The description gives a specific read verb and concretely unpacks the resource: 'dated exposures, recorded historical membership and movement comparisons for a dam/birth date.' An agent knows this is a read of derived birth evidence scoped to a dam + date. It does not, however, distinguish itself from the sibling get_birth_source_evidence, leaving the boundary between the two evidence tools to inference.

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

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

There is no 'use this when' clause and no reference to alternatives such as get_birth_source_evidence, get_birth_event, or list_birth_events. The closest thing to guidance is the caveat that presumed sire evidence is a review proposal, which describes the nature of the data rather than when to reach for 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing what the call returns — producer-configured intervals plus zero-to-many planned birth windows — which is non-obvious for a 'settings' endpoint.

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

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

A single well-formed sentence with no filler, front-loading the read action and immediately qualifying the cardinality of the returned windows ('zero-to-many').

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 usefully summarizes the return payload, which is the main thing an agent needs. The only gap is that it doesn't connect itself to the sibling read tool for birth history evidence or mention farm scoping, but the schema covers the latter.

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 single farm_id parameter is documented in the schema, including its default to the active farm. The description adds no parameter meaning beyond that, so the baseline 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?

States a specific verb ('Read') and resource ('birth history settings'), and enumerates the returned content (species gestation/age intervals, planned birth windows). It is clearly distinguishable from the write counterpart set_birth_history_settings and the related get_birth_history_evidence, though it does not explicitly name those 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?

Usage is implied by the read-only nature of the tool and the existence of set_birth_history_settings as its mutation counterpart, but the description never states when to use this versus get_birth_history_evidence or the set/update tool. No exclusions or prerequisites are given.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds auth requirements (source author's current farm access) and the partial-match behavior (producer selection required). That is meaningful context beyond the structured hints, though no pagination or response-shape notes.

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

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

Two tight sentences with the returned data front-loaded and constraints following. No filler, though the phrasing is jargon-dense enough that a first-time reader may need a second pass.

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 enumerates the main things returned (SMS source, media status, identity candidates) and the key precondition, so an agent can call it correctly. Gaps are limited to parameter-level detail and result paging.

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 0% for both parameters, so the description must carry the burden. It implies the source is an SMS record but never explains what source_sms_id or farm_id mean, their format, or when farm_id is optional versus required.

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 ('Read') plus three concrete resources: retained SMS birth source, ordered media status, and current-farm identity candidates. This is far more specific than the name alone, though it never explicitly contrasts with the close sibling get_birth_history_evidence.

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

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

Gives a real precondition ('Requires the source author's current farm access') and a boundary ('this lookup does not approve identities or save a birth'), which tells the agent when not to expect a write. It stops short of naming an alternative tool for the approve/save path.

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?

readOnlyHint already establishes the safety profile, and the description adds genuine payload context beyond the annotation: the response includes the widget config and the animals processed (entries). With no output schema, this return-content disclosure is a real value-add.

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

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

One sentence, front-loaded with verb+resource, no filler. Every clause earns its place by adding the lookup key and the returned contents.

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 two-parameter read tool, the description covers the lookup key and the notable response contents, and the annotation covers safety. Permissions or pagination are unaddressed, but the small surface area makes this nearly complete.

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

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

Schema coverage is 100%, so both parameters (session_id UUID, optional farm_id with default behavior) are already documented in the schema. The description only echoes the UUID lookup and adds no format or syntax detail beyond it.

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

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

States a specific verb (Get) and resource (a single chute session) with its scope (by its UUID), which clearly separates it from the list_chute_sessions sibling. It does not name any sibling explicitly, so it stops short of a 5.

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

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

The 'single session by UUID' framing implies when to use this versus list_chute_sessions, but there is no explicit when-to-use/when-not guidance or named alternative. Usage is inferable rather than stated.

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

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

The readOnlyHint annotation already establishes that this is a safe read, so the description's main added value is content, and it delivers only one field (default farm ID). With no output schema, the description leaves 'context' undefined and does not say what else is returned, which is a meaningful gap.

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

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

A single, front-loaded sentence with no wasted wording. It is efficient, though its brevity comes partly from under-specification rather than deliberate economy.

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 must explain the return shape, but it only names the default farm ID and leaves the rest of 'context' opaque. For a tool whose entire value is its returned payload, this is incomplete.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies for a no-argument tool.

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 verb (Get) and a resource (current context) and names one concrete payload field, the default farm ID. However, 'context' itself is undefined, and the description does not distinguish this tool from siblings like get_farm or list_my_farms, so an agent cannot fully tell what scope of data it returns.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer that this is the way to discover the active/default farm, and nothing tells it when to prefer set_default_farm or get_farm instead.

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?

readOnlyHint=true is already declared in annotations, so safety is covered by structured data. The description adds no behavioral context beyond that – nothing about permissions, scoping, error behavior if the farm_id is unknown, or what 'details' includes – so it contributes essentially nothing the agent didn't already have.

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

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

A single short sentence with no filler bytes and front-loaded verb+object. It is efficient, though brevity here edges toward under-specification rather than tightness.

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 one-parameter read tool whose annotations and schema are complete, the minimum is met. Still, with no output schema the description could have said what 'details' are returned and how this differs from the other farm-context tools, which would materially help selection.

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 the single farm_id parameter is fully described in the schema as 'The ID of the farm to retrieve'. The description adds no format, source, or constraint details beyond that, so the baseline 3 applies.

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

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

States a clear verb (get) and resource (farm) with scope (a specific farm), which an agent can act on directly. However, it does not distinguish itself from siblings such as list_my_farms or get_current_context, so sibling disambiguation is left to inference.

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

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

There is no guidance on when to use this versus list_my_farms or get_current_context, nor any stated prerequisite that the farm_id must already be known. The agent gets no routing information.

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?

readOnlyHint already establishes the safe-read profile, and the description adds real value beyond that by disclosing the return contents: an ingredient snapshot with targets/actuals and per-group deliveries. This is meaningful behavioral context, especially since there is no output schema.

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

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

A single front-loaded sentence that identifies the resource, the key, and the payload with zero filler.

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

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

For a simple read tool with no output schema, the description usefully summarizes the returned structure and confirms the UUID key. It leaves only minor gaps such as error behavior for an unknown UUID.

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 (farm_id and feeding_id) are already documented in the schema. The description only restates that lookup is by UUID, adding no syntax or format detail beyond what the schema provides.

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

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

States a specific verb (get) and resource (a single feeding), scoped by UUID, plus what the payload contains. The word 'single' implicitly separates it from the sibling list_feedings, though no sibling is named explicitly.

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

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

Usage is implied by the singular lookup semantics, but there is no explicit when-to-use guidance, no mention of when to prefer list_feedings, and no stated prerequisites or exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds one genuinely useful behavioral fact beyond the annotations — that members are included in the response — but says nothing about behavior on a missing/invalid UUID or any access constraints.

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

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

A single sentence with zero filler; the lookup key and the notable return detail are both 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?

There is no output schema, so the description carries some return-value burden and does disclose that members come back. That covers the main gap; minor omissions are the optional farm_id scoping behavior, already handled by the schema, and error semantics.

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

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

Schema description coverage is 100%, so both group_id and farm_id are already documented in the schema. The description only restates that the lookup is by UUID and adds no format or scoping detail, so the baseline 3 applies.

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

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

States a specific verb (get), resource (group), lookup key (UUID), and the returned payload (including members). It is clearly distinguishable from list_groups by the word 'single', though it never names a sibling explicitly.

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

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

Usage is only implied: an agent can infer this is for fetching one known group versus list_groups for enumeration, but the description gives no explicit when-to-use, when-not-to-use, or alternative routing guidance.

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

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

Annotations only supply readOnlyHint=true; the description adds substantive behavior: outputs are presigned URLs, they expire in 1 hour, access is admin-restricted, and the returned file contents are untrusted data with a prompt-injection warning. That is meaningful context beyond the annotations, though it doesn't discuss pagination or 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?

Three short sentences, each earning its place: the core action first, then the URL expiry, then the security warning. Nothing is redundant or buried.

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 usefully signals what comes back (presigned URLs) and its lifetime, plus the admin gate and untrusted-content caveat. It stops short of explaining error conditions or how the URLs relate to the request lifecycle, but it is largely complete for a single-param read 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 description coverage is 100% for the single import_request_id parameter, so the schema already carries the semantics. The description adds nothing about the ID's format or origin, making 3 the correct baseline.

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

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

States a specific verb (Get), resource (import request), and even clarifies the payload (presigned download URLs for its files), which is more than the title offers. It does not, however, distinguish itself from closely related siblings like list_pending_imports or update_import_request_status.

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 '(admin only)' qualifier gives a real prerequisite that constrains who can call it. But there is no guidance on when to use this versus list_pending_imports or after update_import_request_status, so the selection context is only implied.

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, so the safety profile is covered. The description adds useful behavioral context by disclosing that the call returns nested sublocations and premises identifiers, which matters given there is no output schema. It does not mention permissions, error behavior, or depth of sublocation recursion.

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

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

A single compact sentence with no filler, front-loaded with the verb and resource. It earns its place by combining the fetch action and the return contents, though it is terse enough to leave gaps rather than being padded.

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

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

For a simple read-by-id tool with annotations covering safety, the description is roughly adequate, and it usefully summarizes the return payload absent an output schema. However, the unexplained farm_id parameter and lack of any usage routing leave gaps an agent must guess at.

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 only 50%: location_id is documented ('Location UUID.') but farm_id has no description anywhere. The description adds no parameter detail, so it fails to compensate for the undocumented farm_id or clarify its role relative to location_id.

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 ('Get') and resource ('location') and goes further by naming what the response contains: sublocations and premises identifiers. This distinguishes it from list_locations (plural) but does not explicitly contrast with get_farm or other singular getters, so it stops short of full sibling differentiation.

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 no when-to-use guidance and names no alternatives. It never says to use this over list_locations when a single UUID is known, nor when farm_id should be supplied. Usage is only weakly implied by the singular 'one location'.

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 readOnlyHint annotation already makes the safe-read nature clear. The description adds useful return context by noting ingredients in load order and group assignments, but does not mention error behavior, permissions, or whether missing rations return an error.

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 a single, front-loaded sentence with no wasted words. It places the key lookup key and returned data in an efficient order.

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

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

For a simple read-only lookup with a fully documented schema and annotations, this is largely complete. It describes the main returned content, though without an output schema the agent still lacks a full picture of all possible response fields.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that lookup is by UUID but adds no syntax or constraint details beyond the schema for ration_id or farm_id.

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 single feed ration by UUID. The word "single" plus the described ingredients and group assignments distinguish it from list_rations, though no sibling is named explicitly.

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

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

The description implies usage by saying lookup is by UUID, which suggests fetching one known ration rather than listing rations. It does not explicitly say when to use this versus list_rations or other ration-related 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?

The readOnlyHint annotation already establishes this is a safe read, so the description's remaining job is to add context. It does add one useful non-obvious detail — the response includes affected animals/groups — which is real value since no output schema exists, but it says nothing about farm scoping behavior or error 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?

A single front-loaded sentence with the resource, the required identifier, and the payload scope. No filler or 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-item read with readOnly annotations and full schema coverage, the definition is nearly sufficient, and it partially compensates for the missing output schema by naming what the record includes. It lacks any note on behaviour when farm_id is omitted or the record is not found.

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

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

Schema description coverage is 100%, so both parameters (farm_id, record_id) are already documented in the schema; the description only restates record_id as a UUID. Baseline 3 applies when the schema carries parameter semantics.

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

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

States a specific verb and resource ('Get a single record') and adds the key identifier ('by its UUID'), so it is clearly distinct from list_records/create_record/update_record. It does not explicitly name a sibling, so it stops short of a 5.

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

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

Usage is only implied: 'by its UUID' tells the agent it needs a known record ID, which is enough to infer it should be used after a listing or creation step rather than for discovery. No explicit when/when-not or pointer to list_records for searching.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's job is to add context. It does disclose the shape of what comes back (revision, projections, links), which is useful given there is no output schema, but it says nothing about not-found behavior, permissions, or scoping by farm_id.

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

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

A single front-loaded sentence with no filler. Every clause adds information: singular scope, the typed nature of the event, and the returned components.

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 two-parameter read with no output schema, the description gives a usable sketch of the return payload but omits parameter meaning and error/empty-case behavior. Adequate but with clear gaps an agent would need to guess at.

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 0%, so the description must carry the burden for two parameters and it carries none. It never explains what event_id identifies, whether it is a UUID or a typed key, or what the optional farm_id scopes or overrides.

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 (Get) and resource (one typed traceability event) and names the payload components (current revision, projections, links). 'One typed event' implicitly distinguishes it from list_traceability_events and get_traceability_event_revisions, but it never names those siblings explicitly.

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

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

No statement of when to use this tool versus list_traceability_events, get_traceability_event_revisions, or correct/void_traceability_event. The only hint is 'one', which implies a single-entity fetch rather than a list, leaving the agent to infer the routing decision.

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 readOnlyHint annotation already tells the agent this is a safe read. The description adds genuinely useful behavioral context beyond that: the result set includes superseded and voided facts, not just live ones. It does not mention ordering, pagination, or farm scoping, so it stops short of rich 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?

A single front-loaded sentence with no filler; the scope qualifier ('including superseded and voided facts') lands immediately after the core action.

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

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

For a simple read-only list tool with no output schema, the description is close to sufficient, and it correctly clarifies that historical facts are included. It leaves the farm_id parameter and any result ordering or size limits undocumented, which is a real gap given 0% schema coverage.

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 0%, so the description carries the full burden and says nothing about either parameter. event_id's role is inferable from the tool name, but farm_id is entirely unexplained — whether it scopes the query, is required, or alters results is unknowable from both schema and description.

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

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

States a specific verb ('List') and resource ('stored revision of a typed event') and clarifies scope with 'including superseded and voided facts'. An agent can distinguish it from get_traceability_event (current state) and correct_/void_traceability_event (mutations), though the sibling differentiation is implicit rather than named.

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

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

No explicit when-to-use or when-not statement, and no alternatives are named. However, 'including superseded and voided facts' implies the audit/history use case (e.g., after a correction or void), which is enough to imply intent but not to route decisively.

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, so the safety profile is covered. The description adds meaningful context beyond that: the ownership authorization requirement and the conditional behavior that a committed preview returns its saved outcome. It still doesn't say what happens for uncommitted previews.

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

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

Two tight sentences, no filler, with the ownership constraint and read-only nature front-loaded. Every clause earns its place.

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

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

With no output schema, the description does note the committed-outcome behavior, and annotations cover safety. However, it omits what an uncommitted preview returns and adds nothing for the undocumented required preview_id, leaving the picture partly incomplete.

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 50%: farm_id is documented in the schema, but the required preview_id has no description in either the schema or the description. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap.

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 (read) and resource (an authorized preview plus its saved outcome when committed), which cleanly separates it from the sibling preview_workflow that produces previews. It does not explicitly name any sibling, but the 'get existing preview' framing is unambiguous.

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

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

The precondition 'the requesting actor must be the preview owner' is a useful gating rule, but there is no explicit when-to-use guidance relative to preview_workflow, commit_workflow, or discard_workflow. Usage is implied by the read-existing framing rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only' is redundant. The one genuinely additive fact is that the response spans the template plus every published version, but nothing is said about version ordering, pagination, or behavior for archived/missing templates.

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

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

Two short sentences, zero filler, with the resource and scope front-loaded and the safety profile trailing. Every clause 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?

For a simple get-by-id read whose annotations already carry the safety profile, the description covers the essentials. However, with no output schema, the description should have described the returned structure (template fields, version list shape) more than the single clause 'every published version'.

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 50%: farm_id is documented in the schema (with its active-farm default) while template_id is undocumented in both places. The description's phrase 'farm-owned' loosely gestures at the farm scoping but adds no format or constraint detail, so baseline 3 is appropriate at this borderline coverage.

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 ('Read') plus resource ('workflow template') with scope modifiers: a single farm-owned template plus every published version. The word 'one' implicitly separates it from the sibling list_workflow_templates, but no sibling is named, so the differentiation is inferential rather than explicit.

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

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

Usage is only implied by the scope ('one ... template'). There is no statement of when to reach for this versus list_workflow_templates, get_workflow_preview, or commit_workflow, and no prerequisites or error conditions are mentioned.

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?

readOnlyHint already declares a safe read. The description adds genuine behavioral context beyond that: pagination is optional, the default match is exact and case-sensitive, partial matching is opt-in, and inventory_status ALL surfaces historical profiles. It omits auth/permission requirements and any rate limits.

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

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

Three sentences, front-loaded with the core purpose, each adding distinct information. The final clause ('explicit partial substring discovery') is slightly dense but earns its place by defining match_mode behavior.

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 7-parameter, zero-coverage, no-output-schema tool, the description covers the expressive parts (query, matching, status, pagination) but leaves farm_id and identifier_type unexplained. Return values need not be described since no output schema exists, so the main gap is parameter coverage.

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 0% schema description coverage, the description must carry parameter meaning and it does for query, match_mode ('exact equality by default (case-sensitive), or explicit partial substring discovery'), and inventory_status. But farm_id, identifier_type, and the skip/take bounds are never explained, leaving three of seven parameters undocumented anywhere.

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 ('List current animals on the farm') and qualifies the scope with pagination and inventory-status options. It implicitly separates itself from lookup siblings like find_animal_by_identifier and get_animal, though it never names an alternative explicitly.

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

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

Offers usage guidance for parameters ('Select an inventory status or ALL to discover historical profiles', 'With a query, search saved identifiers...'), which tells the agent how to drive the tool. However it never states when to prefer this over siblings such as find_animal_by_identifier or list_identifiers, leaving the routing decision 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results are 'saved' events (implying drafts/previews are excluded) and that pagination is bounded, but says nothing about ordering, default page size, or total counts.

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

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

A single front-loaded sentence with no filler; pagination and filtering are surfaced immediately. It is efficient, though slightly too terse given the parameter coverage gap.

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 and 0% schema description coverage on 4 parameters, the description carries the burden and falls short. An agent still lacks default page size, sort order, whether farm_id or animal_id is required for meaningful results, and what a birth event record contains.

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 0% across 4 parameters, so the description must compensate and largely does not: it mentions filtering by 'dam or offspring' (loosely animal_id) but omits farm_id entirely and gives no offset/limit semantics for skip/take. The mapping from 'dam/offspring' to animal_id is left for the agent to guess.

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

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

States a specific verb (List) and resource (saved birth events), and the sibling names (get_birth_event, preview_birth_event, confirm_birth_event) make the list-vs-single-vs-write distinction inferable. However the stated filters ('dam or offspring') do not name the actual schema fields (farm_id, animal_id), which blurs exactly what can be filtered on.

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

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

No guidance on when to call this versus get_birth_event, preview_birth_event, or the other list_* tools. The word 'saved' hints at excluding drafts/previews, but no alternative is named and no exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the meaning of PROPOSED (assistant-built, awaiting in-app confirmation) and ACTIVE (resumable draft), which tells the agent these are workflow-state artifacts. However nothing is said about pagination defaults, result ordering, or scope limits.

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

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

Two sentences, front-loaded with the core action and scope, and the status semantics are attached to the filter they describe. The parenthetical example list is slightly dense but earns its place by disambiguating the domain term.

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, no parameter descriptions, and four parameters, the description should carry more weight. It defines the resource and the status filter well but omits pagination behavior (take caps at 200) and the farm_id scoping rule, which an agent needs to call this list tool correctly.

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

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

Schema description coverage is 0% across 4 parameters, so the description must compensate. It fully documents the status enum values, which is the parameter most likely to be misused, but says nothing about skip/take pagination semantics or farm_id scoping, leaving half the surface undocumented.

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 chute-mode work sessions on the farm') and immediately defines what a chute session is with concrete examples (weigh days, preg checks, vaccinations). This distinguishes it from sibling list tools such as list_records, list_workflow_templates, and list_farm_tasks.

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

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

The description explains the purpose of the status filter and what each status means, which implies when the filter is useful, but it never states when to call list_chute_sessions versus get_chute_session or the other session-related siblings. Usage context is present but no explicit alternatives or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral fact — that undated todos are returned — but says nothing about pagination behavior despite the presence of skip/take parameters.

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

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

A single short, front-loaded sentence with no filler. It is arguably too terse rather than verbose, which is a completeness issue rather than a conciseness one.

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 four-parameter list tool with 0% schema coverage and no output schema, the description leaves pagination, filtering, and farm scoping entirely unexplained. The only scope detail given is that undated todos are included, which is far short of what an agent needs.

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 0% for all four parameters, and the description explains none of them. It does not clarify that status accepts TODO/DONE/CANCELLED, that take is capped at 200, or how farm_id scopes the list, so it fails to compensate for the schema gap.

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 pairs the verb "List" with a specific resource ("farm follow-up work") and clarifies scope by noting undated todos are included. It does not, however, differentiate this from nearby siblings such as update_farm_task or list_workflow_templates, so the agent must rely on the name alone for disambiguation.

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

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

There is no guidance on when to call this versus alternatives (e.g., update_farm_task, list_workflow_templates) and no stated prerequisites such as whether farm_id is needed to scope results. Usage is only implied by the verb "List".

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that: newest-first ordering and the fact that each row carries ration, status, batch scale factor, and total pounds delivered. It says nothing about pagination behavior or result-set size, which matters for a list endpoint.

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

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

Two compact sentences, front-loaded with the action and scope, then the returned content. Every clause carries information and nothing is padded.

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

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

With no output schema, the sentence describing returned fields (ration, status, batch scale factor, total pounds) usefully covers the response shape. However, the five undocumented filter/pagination parameters and unstated result limits leave real gaps for an agent trying to invoke it correctly.

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

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

Schema description coverage is 0% across five parameters (skip, take, since, status, farm_id), and the description explains none of them - not what 'since' means, not the ACTIVE/COMPLETED status values, not the take maximum. The mention of 'status' refers to a returned field, not the filter argument, so it does not compensate.

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 feedings') and immediately disambiguates the domain term by glossing it as 'executed mixer loads', plus adds the ordering ('newest first'). It does not explicitly separate itself from the nearby get_feeding/list_rations siblings, so it falls short of the 5-mark sibling differentiation bar.

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

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

There is no when-to-use guidance, no mention of when to prefer get_feeding over this list call, and no reference to the available filters (farm_id, status, since) or pagination. Usage must be inferred from the name alone.

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

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

readOnlyHint=true already declares this as a safe read, so the description only needs to add context beyond that. It adds nothing: no pagination behavior, no result ordering, no auth/permission notes, and no indication of what happens when farm_id is omitted.

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

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

One short, front-loaded sentence with no padding. It is efficient, though 'on the farm' is slightly redundant given the resource is already farm-scoped.

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 one-parameter read-only list tool this is close to adequate, but with no output schema the description should at least indicate what a group record contains or how many/which groups are returned. That gap keeps it at minimum-viable.

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 a single optional parameter fully documented, including the 'optional if a default is set' caveat, so the baseline is 3. The phrase 'on the farm' loosely reinforces the farm scoping but adds no syntax or default-resolution detail beyond the schema.

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

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

States a clear verb+resource: 'List animal groups.' The plural verb distinguishes it from the singular get_group sibling, but the description never names or contrasts any sibling (create_group, update_group, restore_group) explicitly.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_group for a single group. The agent must infer that this is the bulk-listing counterpart from the tool name alone.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lower, but it still adds nothing: no pagination or ordering behavior, no statement of what happens when the animal has no identifiers, no permission context.

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

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

A single sentence, front-loaded with the verb and resource, containing the enumerated return types with zero filler.

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

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

For a simple two-parameter read tool with annotations covering safety and no output schema, the description conveys both the scope and the kinds of identifiers returned, which is enough to call it correctly. Only the lack of routing to sibling identifier tools is a gap.

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

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

Schema description coverage is 100% (animal_id documented as the animal UUID, farm_id as optional with a default), so the schema carries parameter meaning. The description only restates that the lookup is per-animal and adds nothing about farm scoping when multiple farms are accessible.

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

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

States a specific verb (List) and resource (identifiers) and enumerates the identifier kinds returned (tags, names, EID, brand, tattoo), scoped to a single animal. It is distinguishable from list_animals and find_animal_by_identifier, though it does not name the adjacent sibling it is not.

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 'for a given animal' clause implies the trigger, but there is no explicit when-to-use guidance, no mention of alternatives such as find_identifier_history or find_animal_by_identifier, and no stated prerequisites (e.g., needing an animal UUID from list_animals).

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

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

With readOnlyHint=true already declaring the safety profile, the description adds useful behavioral context: archived locations are excluded by default, include_archived overrides this, and entries include parent path and premises identifiers. It does not discuss permissions or pagination, but the read-only annotation lowers the burden.

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

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

Three concise sentences, front-loaded with the core purpose and followed by the key default and return-content detail. Every sentence contributes useful information with no waste.

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

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

For a simple two-parameter, read-only list tool with no output schema, the description covers scope, archived behavior, and what each entry carries. It is largely complete, with only minor gaps such as explicit sibling routing or pagination details.

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 schema. The description reinforces include_archived semantics by clarifying the default exclusion behavior, but it adds little beyond the schema for farm_id and does not need to compensate for coverage gaps.

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

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

The description uses a specific verb and resource: 'List farm locations (premises and sublocations)'. This clearly distinguishes it from sibling tools like get_location, create_location, archive_location, and restore_location, though it does not explicitly name those alternatives.

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

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

Usage is implied: list locations for a farm, optionally including archived ones. The description does not say when to prefer this over get_location or list_animals, nor does it give explicit when-not guidance beyond the archived default.

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 readOnlyHint annotation already establishes this is a safe read, so the description's burden is light. It adds useful scoping context (memories belong to the current farm, one current value per key) but says nothing about pagination, volume of results, or what happens if nothing is stored.

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

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

Two tight sentences: the what comes first, the when-to-use second. Nothing is redundant or padded.

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

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

For a read-only, single-optional-param list tool with annotation coverage, the description supplies purpose, scoping, and a usage cue. No output schema exists, so the description could say more about the returned key/value shape, but 'current value per key' covers the essential structure.

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

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

Schema description coverage is 100% with a single optional farm_id parameter, so the schema already documents the input fully. The description only gestures at farm scoping ('about this farm') without adding format or default-resolution details beyond the schema.

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

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

States a clear verb (list) and resource (assistant memories about this farm), and the parenthetical 'the current value per key' sharpens what is actually returned. It implicitly separates itself from farm-data siblings like list_my_farms and get_farm, though no sibling is named explicitly.

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

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

'Use before saving a memory to avoid duplicate or conflicting keys' gives explicit when-to-use guidance tied to a concrete workflow. It does not name or exclude any alternative tool, but no obvious sibling overlaps with this capability.

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?

readOnlyHint=true already tells the agent this is a safe read. The description usefully adds the permission-scope detail ('farms that the user has access to'), but says nothing about pagination, result size, or ordering.

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

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

A single short sentence with no wasted wording, and the scope qualifier is front-loaded.

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

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

For a zero-parameter read-only list tool with annotations covering the safety profile and no output schema, the description is nearly sufficient. A brief note on return contents or pagination would close the 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?

Zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond scope, which it already covers.

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

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

The description gives a specific verb ('List') and resource ('farms') and scopes it to 'farms that the user has access to'. It is clearly distinct from the singular get_farm, though it does not explicitly name or contrast that sibling.

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

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

No when-to-use context, no mention of alternatives like get_farm or set_default_farm, and no stated purpose for listing (e.g., discovering farm IDs). Usage is only implied by the verb.

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

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

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds genuine context beyond annotations: the cross-farm scope and the admin-only authorization requirement, which the agent cannot infer from 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?

Two compact sentences, front-loaded with the resource and scope, and the default behavior stated last. Every clause 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?

For a read-only list tool with annotations covering safety and no output schema, the description is mostly adequate. But the pagination parameters are undocumented and no return-shape or result-limit context is given, leaving gaps an agent would need to resolve by experimentation.

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 0%, so the description must carry the load. It only clarifies the status parameter (defaults to PENDING) and says nothing about skip/take pagination, leaving two of three parameters undocumented in both the schema and the description.

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

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

States a specific verb (List) and resource (concierge import requests), plus a scope (across all farms) that distinguishes it from the single-item sibling get_import_request. It does not explicitly name that sibling, so it falls short of a 5.

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

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

"Defaults to PENDING status" and "(admin only)" imply when the tool is applicable and who can call it, giving useful implied context. However, there is no explicit guidance on when to use this versus get_import_request or update_import_request_status.

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=false, so the safety profile is covered. The description adds useful context that definitions are immutable and pagination is bounded, but it does not explain pagination behavior or access requirements.

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

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

Two short sentences with the main purpose front-loaded, so it is efficient overall. The final sentence is slightly extraneous but not enough to hurt conciseness.

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

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

For a list tool with no output schema and three undocumented parameters, the description leaves out how to scope by farm_id and how pagination should be used. The annotations cover safety, but the remaining functional gaps are significant.

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 0% for all three parameters. "Bounded pagination" hints at skip/take, but farm_id is never explained, and no parameter constraints or semantics are added beyond the schema types.

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 immutable farm protocol definitions," with scope clarified by "bounded pagination." It does not explicitly distinguish itself from create_protocol_version or workflow-template siblings, so it is clear but not fully differentiated.

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

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

Gives no explicit when-to-use guidance versus create_protocol_version or the workflow-template tools. "Never invent missing steps" is an agent instruction, not a condition for selecting this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful domain context (what fields a ration carries) but says nothing about pagination behavior, default result size, whether inactive rations are included by default, or whether farm_id is effectively required despite the schema showing zero required parameters.

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

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

A single dense sentence that front-loads the verb and resource, with the clarifying gloss trailing after the colon. Nothing is wasted, but there is no structure for the filtering/pagination information an agent would need.

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 four-parameter listing tool with no output schema and no schema descriptions, the definition should carry more weight. It omits pagination semantics, the effective requirement for farm_id, and the meaning of include_inactive, leaving gaps an agent cannot resolve from structured data.

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 0% and none of the four parameters (skip, take, farm_id, include_inactive) are explained anywhere. The phrase 'on the farm' faintly implies farm_id, but the description does not clarify its role, nor the default for include_inactive, nor the pagination contract.

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 (List) plus resource (feed rations) with a domain gloss that explains what a ration actually is: named recipes in per-head-per-day amounts with ingredients and group assignments. This is well beyond a tautology. It does not explicitly distinguish itself from the sibling get_ration, so it stops short of a 5.

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

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

There is no statement of when to use this versus get_ration, create_ration, or list_feedings, and no guidance on how the pagination or filtering parameters should be used. The agent must infer that this is the bulk-listing counterpart to get_ration.

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=true, so the description carries most of the burden and delivers real value: result-size behaviour (default 50, max 200) and scoped-credential requirements (read:animals for animal_id, read:groups for group_id, both for include_group_context). It does not describe ordering, cursor/skip behaviour, or the return shape, which are still open.

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

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

Three sentences, purpose and default behaviour front-loaded, then the mode switch, then the credential constraints. Dense and free of filler, though the third sentence packs three separate auth conditions into one long clause.

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

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

For a 9-parameter, zero-required, read-only list tool with no output schema, the description covers purpose, bounding modes, page size, and auth scoping, but leaves skip/take/type/farm_id semantics and the response shape entirely unexplained. Adequate for a simple list endpoint, but noticeably incomplete given how many parameters exist.

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 0% across 9 parameters, so the description must compensate and only partly does: it explains animal_id, group_id, applied_from/applied_before, include_group_context, and indirectly the take limit (default 50, max 200). skip, take (by name), type, and farm_id get no semantic explanation anywhere, leaving several parameters undocumented.

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 (list) and resource (records), with a parenthetical that defines what a record actually is (events applied to animals or groups, e.g. feed/health/movement), and it distinguishes two reading modes: an ordinary farm-wide list versus a bounded history read. The only gap is that it never names a sibling (get_record, create_record, list_traceability_events) to route the agent, so differentiation is implicit rather than explicit.

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 states the condition that changes behaviour: with no target or time bound it is the ordinary farm-wide list, and with animal_id, group_id and/or applied_from/applied_before it becomes a bounded history read. That is actionable context, though it stops short of naming alternative tools for overlapping cases (e.g. traceability events).

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 the description adds a genuinely non-obvious behavioral rule: voided events are filtered out by default and only surfaced via include_void. It says nothing about pagination behavior despite skip/take parameters existing.

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

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

Two short sentences, front-loaded with the resource and followed by the key filtering caveat. No filler.

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

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

With 6 undocumented parameters, no output schema, and only a readOnly hint, the description is too thin for the tool's surface. It omits pagination semantics, the meaning of the kind filter, and what the returned events contain.

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 0% across 6 parameters. The description only clarifies include_void indirectly and says nothing about kind's nine enum values, the movement boolean, skip/take pagination limits, or farm_id. With zero schema documentation, the description leaves most parameters unexplained.

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 clear verb+resource ('List typed traceability events on the farm'), and the phrase 'typed' hints at the kind enum. It implicitly distinguishes itself from the singular get_traceability_event, but doesn't name siblings explicitly.

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

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

The description explains the void-exclusion default, which is useful usage context, but gives no guidance on when to choose this over list_animals, traceability_report, get_traceability_event, or list_birth_events. Usage is implied rather than routed.

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=false, so the 'Read-only' sentence is largely redundant. However, the description adds genuine context the annotations do not cover: that results include each template's current published version and that sheep farms get seeded with Detailed and Minimal lambing starters.

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 short sentences, front-loaded with the core action and no filler. Each sentence contributes either scope, return content, or domain behavior.

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 list tool whose annotations cover the safety profile, the description adequately conveys what is returned. It falls short on the four undocumented parameters (notably skip/take pagination) and has no output schema to compensate, so an agent lacks paging and filtering semantics.

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